@xeplr/ui-charts 1.0.1 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xeplr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -33,6 +33,51 @@ import { XeplrChart } from '@xeplr/ui-charts';
 ECharts-mirror `<Chart spec={…} />` (backed by `buildOption`) is also exported for
 callers who'd rather author ECharts-shaped specs directly.
 
+### `chartType`
+
+An **ECharts series type** — `bar`, `line`, `pie`, `scatter`, or any other,
+including one you registered yourself. ECharts is the vocabulary; anything it
+accepts flows through untouched.
+
+Three aliases cover the charts every UI offers that ECharts has no series type
+for. Each resolves to a real type *before* anything reaches ECharts, so an
+unrenderable series is never handed over:
+
+| you say | ECharts gets |
+|---|---|
+| `area`  | `line` + `areaStyle` |
+| `donut` | `pie` + `radius: ['45%','70%']` |
+| `hbar`  | `bar` with the axis roles swapped — category on y, value on x |
+
+Saying it in ECharts' own terms is the same chart: `chartType:'line'` with a
+series `areaStyle` and `chartType:'area'` produce identical output.
+
+A value axis gets `boundaryGap: [0, '10%']` by default — headroom, so the
+tallest point doesn't sit on the top gridline and an area chart isn't clipped
+flat against it. Nothing is added below, since a baseline belongs at zero. It
+applies to whichever axis carries the value, so `hbar` gets it on x. Set
+`axes.y.boundaryGap` (ECharts' own property, passed through verbatim) to
+override.
+
+Binding follows the type, and three types don't bind through `encode` at all —
+handing them one draws nothing, silently:
+
+| binding | types | shape |
+|---|---|---|
+| cartesian | bar, line, scatter, area… | `encode:{x,y}` + a pair of axes |
+| name/value | pie, donut, funnel, sunburst | `encode:{itemName,value}`, **no axes** |
+| radar | radar | `radar.indicator` from the categories; each measure is one shape over them, sharing one max |
+| treemap | treemap | a flat `series.data` of `{name,value}` — treemap has no dataset support |
+| heatmap | heatmap | **two** category axes + `[x,y,value]` cells + a `visualMap` |
+
+A heatmap crosses two groupings, so it reads a second dimension from
+`axes.x.labels[1]` — `x.labels` has always been the dimension list and other
+charts simply use the first. Given only one it warns rather than drawing a
+single stripe that would look like it worked.
+
+Non-cartesian types are given **no axes at all**, including when the theme
+carries axis styling, which would otherwise draw a bare cross behind the slices.
+
 ## The spec (organized ECharts mirror)
 
 It **is** an ECharts `option`, just organized with sane defaults and two

package/lib/chart-options.js

@@ -9,6 +9,8 @@
 // values, and collects `warnings` for properties ECharts can't express (rather
 // than failing). Pure — no echarts/react imports.
 
+var applyRules = require('./rules');
+
 function chartOptionsToOption(co, opts) {
   co = co || {};
   opts = opts || {};
@@ -70,7 +72,21 @@ function chartOptionsToOption(co, opts) {
     var grid = {};
     var edges = edgesFrom(ca.margin, ca.padding, ctx);
     assign(grid, edges);
-    grid.containLabel = true;
+    // CONTAIN WHAT LABELS?
+    //
+    // containLabel exists to stop axis labels being clipped: ECharts shrinks
+    // the plot inward until the text fits. With both axes hidden there is no
+    // text, so it reserves room for nothing — and a chart asked for zero
+    // margin on every edge still had visible space around it.
+    //
+    // That is exactly the minimalist case: no axes, no legend, no title, and
+    // an explicit margin of 0, which then did not look like 0. Derived rather
+    // than exposed as a setting, because "reserve space for the labels you are
+    // drawing" is not a preference — it is a description of whether any are
+    // being drawn.
+    var xShown = !(co.axes && co.axes.x && co.axes.x.show === false);
+    var yShown = !(co.axes && co.axes.y && co.axes.y.show === false);
+    grid.containLabel = xShown || yShown;
     option.grid = clean(grid);
     if (ca.style && ca.style.background && ca.style.background.color) {
       option.backgroundColor = applyOpacity(ca.style.background.color, ca.style.background.opacity);
@@ -80,17 +96,60 @@ function chartOptionsToOption(co, opts) {
 
   // dataLabel is per-series in ECharts — resolve it now, apply when series exist.
   var seriesLabel;
+  var seriesLabelLayout;
+  var seriesLabelLine;
   if (co.dataLabel) {
     var dl = co.dataLabel;
     seriesLabel = clean(assign(
       {
         show: dl.show !== false,
         position: labelPosition(dl.positioning),
-        formatter: dl.formatter
+        formatter: dl.formatter,
+        // The gap between a label and the mark it belongs to.
+        distance: parseSize(dl.distance, ctx),
+        rotate: dl.rotate,
+        // A nudge for ALL of them. Per-label nudging is labelLayout's job.
+        offset: (dl.offsetX != null || dl.offsetY != null)
+          ? [parseSize(dl.offsetX, ctx) || 0, parseSize(dl.offsetY, ctx) || 0]
+          : undefined,
+        minMargin: parseSize(dl.minMargin, ctx),
+        width: parseSize(dl.maxWidth, ctx),
+        overflow: dl.overflow
       },
       fontToTextStyle(dl.font, ctx, 'dataLabel.font'),
       styleToEcharts(dl.style, ctx, 'dataLabel.style')
     ));
+
+    // THE CALLOUT — the leader line out to the label. Native to pie, donut and
+    // funnel; other types ignore it, so it is emitted whenever asked for
+    // rather than gated on a type the caller may know better than we do.
+    if (dl.labelLine) {
+      var ll = dl.labelLine;
+      seriesLabelLine = clean({
+        show: ll.show !== false,
+        length: parseSize(ll.length, ctx),
+        length2: parseSize(ll.length2, ctx),
+        smooth: ll.smooth,
+        minTurnAngle: ll.minTurnAngle,
+        lineStyle: clean({
+          color: ll.lineStyle && ll.lineStyle.color,
+          width: parseSize(ll.lineStyle && ll.lineStyle.width, ctx),
+          type: lineType(ll.lineStyle && ll.lineStyle.style)
+        })
+      });
+    }
+
+    // COLLISION. The usual reason a chart's labels are unreadable is that
+    // they overprint each other, and ECharts can resolve it for the whole
+    // series — worth reaching for before anybody starts nudging labels one at
+    // a time.
+    var layout = dl.layout || {};
+    if (layout.hideOverlap != null || layout.moveOverlap) {
+      seriesLabelLayout = clean({
+        hideOverlap: layout.hideOverlap,
+        moveOverlap: layout.moveOverlap
+      });
+    }
   }
 
   // ── data + series (field-binding via axes.x/y.labels) ──
@@ -99,30 +158,228 @@ function chartOptionsToOption(co, opts) {
 
   var xLabels = co.axes && co.axes.x && co.axes.x.labels;
   var yLabels = co.axes && co.axes.y && co.axes.y.labels;
-  var xField = Array.isArray(xLabels) ? xLabels[0] : undefined;
+  var xField = Array.isArray(xLabels) ? labelField(xLabels[0]) : undefined;
+
+  // What ECharts is actually being asked for. `chartType` is an ECharts series
+  // type — the aliases below resolve to one, so nothing ECharts cannot read
+  // ever reaches it.
+  var shape = resolveChartType(co.chartType);
 
   // per-type mark defaults (theme.marks[chartType]) — line width, bar radius +
   // surface gap, symbol sizes, pie ring. Applied to every series of this type.
-  var marks = co.marks && co.chartType ? co.marks[co.chartType] : null;
-
-  if (co.chartType && Array.isArray(yLabels) && yLabels.length) {
-    option.series = yLabels.map(function (yf) {
-      var ser = clean({
-        type: co.chartType,
-        name: yf,
-        encode: xField ? { x: xField, y: yf } : { y: yf },
-        label: seriesLabel
+  // Looked up under the NAME that was asked for first, so a theme can style
+  // `donut` apart from `pie`, then under the type it resolves to.
+  var marks = co.marks && co.chartType
+    ? (co.marks[co.chartType] || co.marks[shape.type])
+    : null;
+
+  var rows = Array.isArray(co.data) ? co.data : [];
+
+  if (shape.type && Array.isArray(yLabels) && yLabels.length) {
+    if (shape.binding === 'radar') {
+      // A radar has its own coordinate system. The CATEGORIES become the axes
+      // (indicators) and each measure becomes one shape laid over them — which
+      // is the transpose of every other chart here, and why it cannot go
+      // through encode.
+      var indicators = categoriesOf(rows, xField).map(function (c) { return { name: String(c) }; });
+      // One shared max, so two measures on the same radar can be compared.
+      // Per-axis maxima would rescale every spoke independently and make the
+      // shape meaningless.
+      var peak = 0;
+      yLabels.forEach(function (l) {
+        rows.forEach(function (r) {
+          var v = Number(r[labelField(l)]);
+          if (isFinite(v) && v > peak) peak = v;
+        });
       });
-      if (marks) applyMarks(ser, co.chartType, marks, ctx);
-      return ser;
-    });
-    // cartesian roles: x carries the category, y the value
-    if (option.xAxis) { if (option.xAxis.type === undefined) option.xAxis.type = 'category'; }
-    else if (xField) option.xAxis = { type: 'category' };
-    if (option.yAxis) { if (option.yAxis.type === undefined) option.yAxis.type = 'value'; }
-    else option.yAxis = { type: 'value' };
+      if (peak > 0) indicators.forEach(function (ind) { ind.max = peak; });
+      option.radar = clean({ indicator: indicators });
+      option.series = [clean({
+        type: 'radar',
+        data: yLabels.map(function (label) {
+          return {
+            name: labelName(label),
+            value: rows.map(function (r) { return r[labelField(label)]; })
+          };
+        }),
+        label: seriesLabel,
+        labelLayout: seriesLabelLayout,
+        labelLine: seriesLabelLine
+      })];
+      delete option.xAxis;
+      delete option.yAxis;
+
+    } else if (shape.binding === 'treemap') {
+      // Treemap has no dataset support at all — it reads series.data, and each
+      // node is {name, value}. One measure: a rectangle has one area.
+      var tf = labelField(yLabels[0]);
+      option.series = [clean({
+        type: 'treemap',
+        data: rows.map(function (r) {
+          return { name: String(r[xField]), value: Number(r[tf]) };
+        }).filter(function (d) { return isFinite(d.value); }),
+        label: seriesLabel,
+        labelLayout: seriesLabelLayout,
+        labelLine: seriesLabelLine,
+        breadcrumb: { show: false }
+      })];
+      delete option.xAxis;
+      delete option.yAxis;
+
+    } else if (shape.binding === 'heatmap') {
+      // TWO categorical axes and a value. The second dimension comes from
+      // x.labels[1] — x.labels has always been the dimension list, and every
+      // other chart simply uses the first of them, so a heatmap needs no new
+      // field to say what it needs.
+      var xf2 = Array.isArray(xLabels) && xLabels.length > 1 ? labelField(xLabels[1]) : null;
+      var vf = labelField(yLabels[0]);
+      if (!xf2) {
+        // Said rather than drawn empty. A heatmap is a grid; with one
+        // dimension there is no grid, and rendering a single stripe would look
+        // like a chart that worked.
+        ctx.warn('a heatmap needs two dimensions — give axes.x.labels a second column');
+        option.series = [];
+      } else {
+        var xCats = categoriesOf(rows, xField);
+        var yCats = categoriesOf(rows, xf2);
+        var xAt = {}; xCats.forEach(function (c, i) { xAt[String(c)] = i; });
+        var yAt = {}; yCats.forEach(function (c, i) { yAt[String(c)] = i; });
+        var cells = [];
+        var lo = Infinity;
+        var hi = -Infinity;
+        rows.forEach(function (r) {
+          var v = Number(r[vf]);
+          if (!isFinite(v)) return;
+          if (v < lo) lo = v;
+          if (v > hi) hi = v;
+          cells.push([xAt[String(r[xField])], yAt[String(r[xf2])], v]);
+        });
+        option.xAxis = assign(option.xAxis || {}, { type: 'category', data: xCats, splitArea: { show: true } });
+        option.yAxis = assign(option.yAxis || {}, { type: 'category', data: yCats, splitArea: { show: true } });
+        // A value axis's headroom is meaningless here — both axes are
+        // categorical — and would push the grid off by a phantom cell.
+        delete option.xAxis.boundaryGap;
+        delete option.yAxis.boundaryGap;
+        // Without a visualMap every cell renders the same shade, which is a
+        // heatmap that carries no information.
+        option.visualMap = {
+          min: isFinite(lo) ? lo : 0,
+          max: isFinite(hi) ? hi : 1,
+          calculable: true,
+          orient: 'horizontal',
+          left: 'center',
+          bottom: 0,
+          inRange: Array.isArray(co.palette) && co.palette.length > 1
+            ? { color: [co.palette[co.palette.length - 1], co.palette[0]] }
+            : undefined
+        };
+        option.series = [clean({ type: 'heatmap', data: cells, label: seriesLabel, labelLayout: seriesLabelLayout })];
+      }
+
+    } else {
+      option.series = yLabels.map(function (label) {
+        var yf = labelField(label);
+        var ser = clean({
+          type: shape.type,
+          name: labelName(label),
+          // Cartesian series bind to axes; the rest name a slice and its size.
+          // A pie given {x, y} silently renders nothing — it is looking for
+          // itemName and value and finds neither.
+          encode: shape.cartesian
+            ? (shape.horizontal
+              ? (xField ? { y: xField, x: yf } : { x: yf })
+              : (xField ? { x: xField, y: yf } : { y: yf }))
+            : (xField ? { itemName: xField, value: yf } : { value: yf }),
+          label: seriesLabel,
+          labelLayout: seriesLabelLayout,
+          labelLine: seriesLabelLine
+        });
+        // The alias's own shaping — areaStyle for an area, a ring for a donut.
+        // Applied before marks so a theme can still override it.
+        if (shape.series) assign(ser, shape.series);
+        if (marks) applyMarks(ser, shape.type, marks, ctx);
+        return ser;
+      });
+
+      if (shape.cartesian) {
+        // Axis ROLES, not axis names: one carries the category, the other the
+        // value. A horizontal bar is the same chart with those swapped, which is
+        // how ECharts itself expresses it — there is no 'hbar' series type.
+        var categoryAxis = shape.horizontal ? 'yAxis' : 'xAxis';
+        var valueAxis = shape.horizontal ? 'xAxis' : 'yAxis';
+        if (option[categoryAxis]) {
+          if (option[categoryAxis].type === undefined) option[categoryAxis].type = 'category';
+        } else if (xField) option[categoryAxis] = { type: 'category' };
+        if (!option[valueAxis]) option[valueAxis] = {};
+        if (option[valueAxis].type === undefined) option[valueAxis].type = 'value';
+        // Headroom above the tallest value.
+        //
+        // ECharts ends a value axis exactly at the data's own maximum, so the
+        // highest point sits ON the top gridline and an area chart is clipped
+        // flat against it — it reads as a chart that ran out of room rather than
+        // one that peaked. VALUE_HEADROOM lifts the top of the scale clear of it.
+        //
+        // Applied to whichever axis carries the VALUE, which is x on a
+        // horizontal bar — hence here, where the role is known, rather than in a
+        // theme that can only name x and y.
+        if (option[valueAxis].boundaryGap === undefined) {
+          option[valueAxis].boundaryGap = VALUE_HEADROOM;
+        }
+
+        // ── AND THE RANGE THE HEADROOM APPLIES TO ────────────────────────
+        //
+        // VALUE_HEADROOM above did NOTHING until this line existed. ECharts
+        // ignores boundaryGap on a value axis while `scale` is off: it builds
+        // a rounded range from zero instead, and a percentage extension is
+        // absorbed into that rounding. Measured — [0,'10%'] and no
+        // boundaryGap at all produced the identical axis.
+        //
+        // Which also means the zero baseline was never a decision. It is
+        // ECharts' default for `scale`, nobody set it, and a comment
+        // explaining the `0` in boundaryGap as "a baseline belongs at zero"
+        // described something that value does not do.
+        //
+        // WHICH CHARTS KEEP ZERO, and why it is not a matter of taste:
+        //
+        //   bar        length IS the quantity. Truncate the axis and a 5%
+        //              difference draws as double — the chart states
+        //              something false about the numbers.
+        //   stacked    the segments are cumulative sums from a baseline.
+        //              Move the baseline and they stop adding up to the
+        //              total they are drawn to show.
+        //   filled     an area's fill reads as volume under the curve, so it
+        //              measures from zero the same way a bar does.
+        //
+        // Everything else — a plain line, a scatter — encodes CHANGE, and
+        // zero flattens exactly the variation it was plotted to reveal. A
+        // series moving between 62,000 and 66,000 becomes a straight line
+        // pinned to the top of an empty chart, and shrinking the card makes
+        // it flatter still.
+        var stacked = Boolean(shape.series && shape.series.stack);
+        var filled = Boolean(shape.series && shape.series.areaStyle);
+        var zeroBased = shape.type === 'bar' || stacked || filled;
+        // Only a real value axis: a heatmap is cartesian with TWO category
+        // axes, and `scale` on a category axis means nothing.
+        if (option[valueAxis].type === 'value' && option[valueAxis].scale === undefined) {
+          option[valueAxis].scale = !zeroBased;
+        }
+      } else {
+        // A pie has no axes. Left in place they draw a bare cross behind the
+        // slices — and any axis STYLING the theme carries would be rendered for
+        // a chart that has none.
+        delete option.xAxis;
+        delete option.yAxis;
+      }
+    }
   }
 
+  // ── conditional formatting ──
+  //
+  // Applied AFTER the series exist, because a rule is scoped to one of them
+  // and needs its index, its palette colour and the field it plots. See
+  // rules.js for which ECharts mechanism each target uses and why they differ.
+  applyRules(co, option, ctx);
+
   // ── theme-level extras (carried on ChartOptions by the theme) ──
   // palette → the series color cycle; fontFamily → global text default (ECharts
   // cascades option.textStyle.fontFamily to all text, so per-block family is
@@ -133,6 +390,118 @@ function chartOptionsToOption(co, opts) {
   return { option: option, seriesLabel: seriesLabel, chartType: co.chartType, warnings: warnings };
 }
 
+// ── chart type ───────────────────────────────────────────────────────────
+//
+// ECharts is the vocabulary. `chartType` IS an ECharts series type and anything
+// ECharts accepts flows straight through — including types registered by the
+// consumer, which is why an unrecognised one is passed on rather than refused.
+//
+// The exceptions are the three names every charting UI offers that ECharts has
+// no series type for. They are not new types: each resolves HERE to a real one
+// plus the property that makes it that chart, so what reaches ECharts is always
+// something ECharts can read. An 'area' series would simply not render, and it
+// would not say why.
+//
+//   area        → line, filled
+//   donut       → pie with a hole
+//   hbar        → bar with the axis roles swapped
+//   stackedBar  → bar, stacked
+//
+// A caller who prefers to say it in ECharts' own terms still can: chartType
+// 'line' with a series areaStyle is the same chart, and passes through
+// untouched.
+var ALIAS = {
+  area: { type: 'line', series: { areaStyle: {} } },
+  donut: { type: 'pie', series: { radius: ['45%', '70%'] } },
+  hbar: { type: 'bar', horizontal: true },
+  stackedBar: { type: 'bar', series: { stack: 'total' } },
+  // Stacking is orthogonal to orientation and to fill, so it combines with
+  // both. Named rather than left to the caller to assemble, because
+  // "horizontal AND stacked" is one chart somebody picks off a list, not two
+  // properties they are expected to know compose.
+  stackedHbar: { type: 'bar', horizontal: true, series: { stack: 'total' } },
+  stackedArea: { type: 'line', series: { areaStyle: {}, stack: 'total' } }
+};
+
+// ECharts types that are NOT plotted against a pair of axes. Everything else
+// is assumed cartesian, which is the right default for the types a consumer is
+// most likely to register (bar/line/scatter variants).
+// How far past the tallest value a value axis runs — boundaryGap's
+// [below, above] pair.
+//
+// The point is the '10%' ABOVE: without it a value axis ends exactly at the
+// data's maximum, so the highest point sits on the top gridline and an area
+// chart is clipped flat against it, reading as a chart that ran out of room
+// rather than one that peaked.
+//
+// The `0` below is not a baseline decision and never was. It says only "add no
+// padding underneath", which suits both cases: a zero-based chart is already
+// at zero, and a scaled one should start at its own minimum rather than
+// somewhere arbitrarily below it. What actually holds a bar chart at zero is
+// `scale`, set where the chart's shape is known — see the block that applies
+// this constant. An earlier comment here credited the `0` with that job, which
+// is how a value that does nothing on its own went years without being
+// questioned.
+var VALUE_HEADROOM = [0, '10%'];
+
+var NON_CARTESIAN = {
+  pie: 1, funnel: 1, gauge: 1, radar: 1, treemap: 1, sunburst: 1,
+  sankey: 1, graph: 1, tree: 1, themeRiver: 1
+};
+
+// HOW a type reads its data. Most bind through the dataset with an encode, but
+// three do not — and handing those an encode draws nothing at all, silently.
+//
+//   cartesian  encode {x, y} against a pair of axes            bar, line, …
+//   nameValue  encode {itemName, value}                        pie, funnel
+//   radar      its own coordinate system: indicators + arrays
+//   treemap    a flat {name, value} list; no dataset support
+//   heatmap    cartesian, but TWO category axes and a value    [x, y, v]
+var BINDING = { radar: 'radar', treemap: 'treemap', heatmap: 'heatmap' };
+
+// An axis label is the FIELD to bind, and optionally the name to show for it:
+// either 'revenue' or { field: 'revenue', name: 'Revenue (£)' }.
+//
+// They are separable because the field is a key in the data and the name is
+// for a person to read, and those are rarely the same string. Without this a
+// legend can only ever show the raw column key — which in a BI tool is
+// something like `a1b2c3__orders_total`. ECharts already separates them; this
+// is series.name alongside encode, said once.
+function labelField(label) {
+  return label && typeof label === 'object' ? label.field : label;
+}
+function labelName(label) {
+  if (label && typeof label === 'object') return label.name != null ? label.name : label.field;
+  return label;
+}
+
+function resolveChartType(name) {
+  if (!name) return { type: undefined, cartesian: true, horizontal: false, series: null, binding: 'cartesian' };
+  var alias = ALIAS[name];
+  var type = alias ? alias.type : name;
+  return {
+    type: type,
+    cartesian: !NON_CARTESIAN[type],
+    horizontal: Boolean(alias && alias.horizontal),
+    series: (alias && alias.series) || null,
+    binding: BINDING[type] || (NON_CARTESIAN[type] ? 'nameValue' : 'cartesian')
+  };
+}
+
+// Distinct values of a field, in the order the rows present them. Order comes
+// from the data rather than sorting, so a caller that has already ordered its
+// rows — by month, by rank — keeps that order on the axis.
+function categoriesOf(rows, field) {
+  var seen = {};
+  var out = [];
+  for (var i = 0; i < (rows || []).length; i++) {
+    var v = rows[i][field];
+    var k = String(v);
+    if (!seen[k]) { seen[k] = 1; out.push(v); }
+  }
+  return out;
+}
+
 // theme.marks[chartType] → ECharts series style. Each chart type reads the marks
 // it understands; unknown keys are simply not consulted (no warnings — marks are
 // a theme convenience, not user-authored CSS).
@@ -147,7 +516,23 @@ function applyMarks(ser, type, m, ctx) {
   } else if (type === 'bar') {
     var bit = {};
     if (m.border && m.border.radius != null) bit.borderRadius = parseSize(m.border.radius, ctx);
-    if (m.gap) {   // the 2px surface gap between fills → a same-color border ring
+    // The surface gap between fills, as a border the colour of the page.
+    //
+    // STACKED SERIES ONLY, and that is the whole of it. A border is the only
+    // thing that can separate two segments of one stacked bar — they share an
+    // edge, so no amount of spacing reaches between them.
+    //
+    // Between separate bars it is the wrong tool and an actively destructive
+    // one. A border eats the fill from BOTH sides at a fixed pixel width while
+    // the bar itself narrows with the category count: at 150 categories a bar
+    // is 8.5px and a 2px ring takes 47% of it; at 300 it is 4.2px and the ring
+    // takes all of it, painting the bar the colour of the background. The
+    // chart renders, reports no error, and shows nothing.
+    //
+    // Bars that merely sit next to each other are already separated by
+    // ECharts' own barGap and barCategoryGap, which are percentages and so
+    // hold at any width.
+    if (m.gap && ser.stack) {
       if (m.gap.color != null) bit.borderColor = m.gap.color;
       if (m.gap.width != null) bit.borderWidth = parseSize(m.gap.width, ctx);
     }
@@ -187,9 +572,27 @@ function axisToEcharts(ax, ctx, path) {
   }
   if (ax.ticks) {
     var tk = ax.ticks;
-    a.axisTick = clean({ show: tk.show !== false, length: parseSize(tk.length, ctx) });
+    // `color` is the tick MARK, alongside `length` and `margin` which also
+    // describe the mark. The label's colour is `ticks.font.color`.
+    //
+    // Both used to land on axisLabel.color, where the font one always won by
+    // being assigned second — so `ticks.color` could not take effect at all,
+    // and no tick mark could be coloured. Two controls, one of them dead.
+    a.axisTick = clean({
+      show: tk.show !== false,
+      length: parseSize(tk.length, ctx),
+      lineStyle: clean({ color: tk.color })
+    });
     a.axisLabel = clean(assign(
-      { show: tk.show !== false, rotate: tk.angle, margin: parseSize(tk.margin, ctx), color: tk.color },
+      {
+        show: tk.show !== false, rotate: tk.angle, margin: parseSize(tk.margin, ctx),
+        // The axis says the same numbers the tooltip and the data labels do,
+        // so it takes the same kind of formatter they already take. Without
+        // one, a currency column's axis was the only place in the chart that
+        // could not be told what the numbers mean — and it is the part that
+        // is always on screen.
+        formatter: tk.formatter
+      },
       fontToTextStyle(tk.font, ctx, path + '.ticks.font')
     ));
   }
@@ -198,6 +601,17 @@ function axisToEcharts(ax, ctx, path) {
     a.nameTextStyle = fontToTextStyle(ax.title.font, ctx, path + '.title.font');
     if (ax.title.margin) a.nameGap = parseSize(ax.title.margin.top || ax.title.margin.bottom || ax.title.margin.left || ax.title.margin.right, ctx);
   }
+  // Straight through, in ECharts' own vocabulary and meaning: a boolean or a
+  // [start, end] pair on a category axis, a [min, max] extension on a value
+  // one. Passing it verbatim is deliberate — inventing a second name for a
+  // property ECharts already has is how two vocabularies start.
+  if (ax.boundaryGap !== undefined) a.boundaryGap = ax.boundaryGap;
+  // Whether the axis fits the data or includes zero. Passed straight through
+  // and, because it is set here from the caller's options, it wins over the
+  // per-shape default applied later — which is the whole point: the default is
+  // right for the chart type, and this is for the reader who knows better
+  // about their own numbers.
+  if (ax.scale !== undefined) a.scale = ax.scale;
   return clean(a);
 }
 

package/lib/register.js

@@ -9,17 +9,31 @@
 
 var echarts = require('echarts/core');
 
-var { BarChart, LineChart, PieChart, ScatterChart } = require('echarts/charts');
+var {
+  BarChart, LineChart, PieChart, ScatterChart,
+  // The four that need their own coordinate system or their own data shape.
+  // Registered by default rather than left to the consumer: a chart type the
+  // translator understands but the runtime cannot draw fails as an empty box
+  // with "Unknown series" in the console, which is a worse default than the
+  // few kB these cost.
+  FunnelChart, RadarChart, TreemapChart, HeatmapChart
+} = require('echarts/charts');
 var {
   GridComponent, TooltipComponent, LegendComponent, TitleComponent,
-  DatasetComponent, ToolboxComponent, DataZoomComponent, MarkLineComponent, MarkPointComponent
+  DatasetComponent, ToolboxComponent, DataZoomComponent, MarkLineComponent, MarkPointComponent,
+  // RadarComponent is the radar's AXES — the series alone draws nothing.
+  // VisualMapComponent is what turns a heatmap's numbers into colours; without
+  // it every cell renders the same shade.
+  RadarComponent, VisualMapComponent
 } = require('echarts/components');
 var { CanvasRenderer, SVGRenderer } = require('echarts/renderers');
 
 echarts.use([
   BarChart, LineChart, PieChart, ScatterChart,
+  FunnelChart, RadarChart, TreemapChart, HeatmapChart,
   GridComponent, TooltipComponent, LegendComponent, TitleComponent,
   DatasetComponent, ToolboxComponent, DataZoomComponent, MarkLineComponent, MarkPointComponent,
+  RadarComponent, VisualMapComponent,
   CanvasRenderer, SVGRenderer
 ]);
 

package/lib/rules.js

@@ -0,0 +1,367 @@
+var R = require('@xeplr/rules');
+var matches = R.matches;
+var formatNumber = R.formatNumber;
+
+// CONDITIONAL FORMATTING — "when this column is under zero, make THAT red".
+//
+// A rule has three parts, and the third depends on the second:
+//
+//   WHEN    field, op, value        which column to test, and against what
+//   APPLY   target                  which object on the chart it styles
+//   THEN    then: { … }             only what that object can actually take
+//
+// The point of naming a target is that a chart is not one thing. Colouring the
+// bar, colouring the number printed above the bar, and colouring the category
+// name under it are three different objects with three different vocabularies —
+// a bar has an opacity and no font, an axis label has a font and no opacity.
+// One rule list that cannot say which one it means can only ever style the one
+// somebody guessed at.
+//
+// ── THE MECHANISM PER TARGET, and why they differ ────────────────────────
+//
+// Every one of these is ECharts' own API. They differ because ECharts itself
+// supports different things in different places, which was established by
+// rendering each and reading the output rather than by reading the docs:
+//
+//   mark        itemStyle callbacks.  itemStyle.color accepts a function and
+//               is handed the whole row, so a rule can test any column and any
+//               type — including a string. Verified on bar, line, scatter,
+//               pie, funnel and treemap.
+//
+//   dataLabel   label.formatter + label.rich.  Label STYLE callbacks do not
+//               work: `label: { color: fn }` puts the function's source text
+//               into the SVG's fill attribute. So the styling has to travel as
+//               rich-text markup, which is ECharts' mechanism for styling part
+//               of a string.
+//
+//   axisX/Y     axisLabel.formatter + axisLabel.rich.  axisLabel.color DOES
+//               take a callback — it is documented as (value, index) => color
+//               and it works — but axisLabel.fontWeight does not. Rather than
+//               support colour one way and weight another, both go through
+//               rich, which is one code path and supports everything.
+//
+// THE CONDITION LIVES ELSEWHERE. `matches`, the operators and number
+// formatting are in @xeplr/rules, because "when margin is under zero" is the
+// same question whether the answer paints a bar, a table cell or an arrow —
+// and a table asking it must not have to depend on a charting library. What
+// stays here is the half that genuinely IS ECharts: turning a match into
+// itemStyle callbacks and label formatters.
+//
+// A visualMap is deliberately NOT used, though it was the obvious candidate.
+// It carries three restrictions that are the mechanism's rather than ECharts':
+// it cannot test a string column at all, it paints an unmatched item black,
+// and a second one on the same series replaces the first outright — silently,
+// along with everything the first had coloured. itemStyle callbacks have none
+// of those.
+
+var TARGETS = { mark: 1, dataLabel: 1, axisX: 1, axisY: 1 };
+
+// itemStyle keys a mark rule may set. ECharts accepts a callback for each.
+var MARK_KEYS = [
+  'color', 'opacity', 'borderColor', 'borderWidth', 'borderType',
+  'borderRadius', 'shadowBlur', 'shadowColor', 'shadowOffsetX', 'shadowOffsetY'
+];
+
+// rich-text keys a text rule may set. A subset of what ECharts' rich accepts —
+// the ones that mean something for a single run of text on a chart.
+var TEXT_KEYS = [
+  'color', 'fontStyle', 'fontWeight', 'fontSize', 'fontFamily',
+  'backgroundColor', 'borderColor', 'borderWidth', 'borderRadius',
+  'padding', 'textBorderColor', 'textBorderWidth', 'lineHeight'
+];
+
+// ── the THEN, for text: number formatting ────────────────────────────────
+
+/**
+ * Whether a run of text can carry rich-text styling.
+ *
+ * ECharts' rich markup is `{styleName|text}` and has no escape sequence, so a
+ * value containing a brace or a pipe cannot be wrapped — a `}` inside would
+ * end the run early and the remainder would print unstyled.
+ *
+ * Answered rather than worked around: the text is printed as it is and the
+ * styling is dropped for that one label. Stripping the character would be
+ * silent data corruption, and wrapping it anyway would truncate the value.
+ */
+function richSafe(text) {
+  return String(text).indexOf('{') < 0 && String(text).indexOf('}') < 0 && String(text).indexOf('|') < 0;
+}
+
+// ── applying ─────────────────────────────────────────────────────────────
+
+function pick(source, keys) {
+  var out = null;
+  for (var i = 0; i < keys.length; i++) {
+    if (source[keys[i]] !== undefined) {
+      if (!out) out = {};
+      out[keys[i]] = source[keys[i]];
+    }
+  }
+  return out;
+}
+
+/**
+ * The rules, sorted into the buckets that each get their own mechanism.
+ *
+ * Reported as it goes: a rule that names a target nothing understands, or sets
+ * a property its target cannot take, is dropped HERE with a reason rather than
+ * emitted for ECharts to ignore. A control that appears to work is the failure
+ * this whole module is arranged to avoid.
+ */
+function sortRules(co, option, ctx) {
+  var yLabels = (co.axes && co.axes.y && co.axes.y.labels) || [];
+  var series = option.series || [];
+  var out = { mark: {}, dataLabel: {}, axisX: [], axisY: [] };
+
+  (co.rules || []).forEach(function (rule, i) {
+    var where = 'rules[' + i + ']';
+    if (!rule || !rule.field) { ctx.warn(where + ' names no column to test (ignored)'); return; }
+    if (!rule.op) { ctx.warn(where + ' has no comparison (ignored)'); return; }
+    var target = rule.target || 'mark';
+    if (!TARGETS[target]) { ctx.warn(where + ' applies to "' + target + '", which is not something on a chart (ignored)'); return; }
+
+    var then = rule.then || {};
+    var keys = target === 'mark' ? MARK_KEYS : TEXT_KEYS;
+    var style = pick(then, keys);
+    var changesText = target !== 'mark' && (then.hide || then.format);
+    if (!style && !changesText) {
+      ctx.warn(where + ' sets nothing its target can take, so it would do nothing (ignored)');
+      return;
+    }
+    // Said, because the panel is generated per target and a rule that arrives
+    // with the wrong vocabulary came from somewhere else — a hand-edited
+    // config, or a target changed after the properties were chosen.
+    var stray = Object.keys(then).filter(function (k) {
+      return keys.indexOf(k) < 0 && k !== 'hide' && k !== 'format';
+    });
+    if (stray.length) ctx.warn(where + ' sets ' + stray.join(', ') + ', which "' + target + '" has no such thing (dropped)');
+
+    var entry = { rule: rule, style: style, hide: Boolean(then.hide), format: then.format || null };
+
+    if (target === 'axisX' || target === 'axisY') {
+      // An axis-label formatter is handed the axis's own value and its index,
+      // and nothing else — there is no row to look at. So a rule here can only
+      // test the column that axis is showing.
+      out[target].push(entry);
+      return;
+    }
+
+    var targets = [];
+    if (rule.series) {
+      var idx = -1;
+      for (var s = 0; s < yLabels.length; s++) if (labelFieldOf(yLabels[s]) === rule.series) idx = s;
+      if (idx < 0 || !series[idx]) {
+        ctx.warn(where + ' applies to "' + rule.series + '", which this chart does not plot (ignored)');
+        return;
+      }
+      targets = [idx];
+    } else {
+      for (var t = 0; t < series.length; t++) targets.push(t);
+    }
+    targets.forEach(function (si) {
+      (out[target][si] || (out[target][si] = [])).push(entry);
+    });
+  });
+  return out;
+}
+
+function labelFieldOf(label) {
+  return label && typeof label === 'object' ? label.field : label;
+}
+
+/** The row behind a datum, whatever binding put it there. */
+function rowOf(params) {
+  var d = params && params.data;
+  if (d && typeof d === 'object' && !Array.isArray(d)) return d;
+  return null;
+}
+
+/**
+ * MARKS — one itemStyle callback per property any rule sets.
+ *
+ * The callback returns the FIRST matching rule's value, and the base value
+ * otherwise. The base matters: returning undefined for `color` renders the
+ * mark with no fill at all, so an unmatched bar would disappear rather than
+ * keep its colour. Every other property tolerates undefined, but colour is
+ * given the series' palette entry explicitly.
+ */
+function applyMarkRules(entriesBySeries, option, palette) {
+  Object.keys(entriesBySeries).forEach(function (si) {
+    var entries = entriesBySeries[si];
+    var ser = option.series[si];
+    if (!ser || !entries || !entries.length) return;
+
+    var props = {};
+    entries.forEach(function (e) {
+      Object.keys(e.style || {}).forEach(function (k) { props[k] = 1; });
+    });
+
+    var base = ser.itemStyle || {};
+    var next = {};
+    for (var k in base) next[k] = base[k];
+
+    Object.keys(props).forEach(function (key) {
+      var fallback = base[key] !== undefined
+        ? base[key]
+        : (key === 'color' ? palette[Number(si) % palette.length] : undefined);
+      next[key] = function (params) {
+        var row = rowOf(params);
+        for (var i = 0; i < entries.length; i++) {
+          var e = entries[i];
+          if (!e.style || e.style[key] === undefined) continue;
+          if (matches(e.rule, row ? row[e.rule.field] : undefined)) return e.style[key];
+        }
+        return fallback;
+      };
+    });
+    ser.itemStyle = next;
+  });
+}
+
+/**
+ * DATA LABELS — one formatter and one rich map per series.
+ *
+ * The formatter has to reproduce what the label would have said, because
+ * setting one replaces ECharts' default entirely. `valueField` is what the
+ * series plots; a non-cartesian series labels by name, which is what its
+ * binding put in params.name.
+ */
+function applyLabelRules(entriesBySeries, option, co, ctx) {
+  var yLabels = (co.axes && co.axes.y && co.axes.y.labels) || [];
+  var byName = !(co.chartType === undefined) && isNameValue(co.chartType);
+
+  Object.keys(entriesBySeries).forEach(function (si) {
+    var entries = entriesBySeries[si];
+    var ser = option.series[si];
+    if (!ser || !entries || !entries.length) return;
+
+    if (ser.label && ser.label.formatter) {
+      // Composing with a caller's own formatter is not possible without
+      // knowing what it means to produce. Said plainly, because a rule that
+      // quietly lost to a template set three panels away is unfindable.
+      ctx.warn('a data-label formatter is already set, so conditional formatting on the label is not applied — clear Data labels → Format to use rules');
+      return;
+    }
+
+    var valueField = labelFieldOf(yLabels[Number(si)]);
+    var rich = {};
+    entries.forEach(function (e, n) {
+      if (e.style) rich['r' + si + '_' + n] = e.style;
+    });
+
+    // A COPY. seriesLabel is one object shared by every series, so writing a
+    // formatter into it would give every series this series' rules.
+    var label = {};
+    for (var k in (ser.label || {})) label[k] = ser.label[k];
+
+    label.formatter = function (params) {
+      var row = rowOf(params);
+      var raw = byName ? params.name : (row && valueField != null ? row[valueField] : params.value);
+      var text = raw === null || raw === undefined ? '' : String(raw);
+
+      for (var i = 0; i < entries.length; i++) {
+        var e = entries[i];
+        if (!matches(e.rule, row ? row[e.rule.field] : undefined)) continue;
+        if (e.hide) return '';
+        if (e.format) {
+          var formatted = formatNumber(raw, e.format);
+          if (formatted !== null) text = formatted;
+        }
+        var name = 'r' + si + '_' + i;
+        if (rich[name] && richSafe(text)) return '{' + name + '|' + text + '}';
+        return text;
+      }
+      return text;
+    };
+    if (Object.keys(rich).length) label.rich = rich;
+    ser.label = label;
+  });
+}
+
+function isNameValue(type) {
+  return type === 'pie' || type === 'donut' || type === 'funnel' || type === 'gauge';
+}
+
+/**
+ * AXIS LABELS — the same formatter/rich pair, on the axis.
+ *
+ * An axis-label formatter receives the tick's own value and its index. There
+ * is no row, so a rule here tests what the axis is showing and nothing else —
+ * which is exactly right for "make IPD red" and impossible for "make the IPD
+ * tick red when its margin is negative".
+ */
+function applyAxisRules(entries, option, which, ctx) {
+  if (!entries.length) return;
+  var key = which === 'axisX' ? 'xAxis' : 'yAxis';
+  var axis = option[key];
+  if (!axis) {
+    ctx.warn('a rule styles the ' + (which === 'axisX' ? 'X' : 'Y') + ' axis labels, but this chart has no such axis (ignored)');
+    return;
+  }
+  if (axis.axisLabel && axis.axisLabel.formatter) {
+    ctx.warn('an ' + (which === 'axisX' ? 'X' : 'Y') + ' axis label formatter is already set, so conditional formatting on it is not applied');
+    return;
+  }
+
+  var rich = {};
+  entries.forEach(function (e, n) {
+    if (e.style) rich[which + '_' + n] = e.style;
+  });
+
+  var axisLabel = {};
+  for (var k in (axis.axisLabel || {})) axisLabel[k] = axis.axisLabel[k];
+
+  axisLabel.formatter = function (value) {
+    var text = value === null || value === undefined ? '' : String(value);
+    for (var i = 0; i < entries.length; i++) {
+      var e = entries[i];
+      if (!matches(e.rule, value)) continue;
+      if (e.hide) return '';
+      if (e.format) {
+        var formatted = formatNumber(value, e.format);
+        if (formatted !== null) text = formatted;
+      }
+      var name = which + '_' + i;
+      if (rich[name] && richSafe(text)) return '{' + name + '|' + text + '}';
+      return text;
+    }
+    return text;
+  };
+  if (Object.keys(rich).length) axisLabel.rich = rich;
+  axis.axisLabel = axisLabel;
+}
+
+// ECharts' own default series colours, for the mark fallback when the caller
+// carries no palette. Getting this wrong means marks with no fill.
+var DEFAULT_PALETTE = [
+  '#5470c6', '#91cc75', '#fac858', '#ee6666', '#73c0de',
+  '#3ba272', '#fc8452', '#9a60b4', '#ea7ccc'
+];
+
+/**
+ * Apply every rule on `co` to the option being built.
+ *
+ * Called after the series exist, because a rule is scoped to one of them and
+ * needs its index, its palette colour and the field it plots.
+ */
+function applyRules(co, option, ctx) {
+  if (!Array.isArray(co.rules) || !co.rules.length) return;
+  if (!Array.isArray(option.series) || !option.series.length) return;
+
+  var palette = (Array.isArray(co.palette) && co.palette.length) ? co.palette : DEFAULT_PALETTE;
+  var sorted = sortRules(co, option, ctx);
+
+  applyMarkRules(sorted.mark, option, palette);
+  applyLabelRules(sorted.dataLabel, option, co, ctx);
+  applyAxisRules(sorted.axisX, option, 'axisX', ctx);
+  applyAxisRules(sorted.axisY, option, 'axisY', ctx);
+}
+
+module.exports = applyRules;
+// Re-exported so an existing caller keeps working; the source of truth is
+// @xeplr/rules.
+module.exports.matches = matches;
+module.exports.formatNumber = formatNumber;
+module.exports.richSafe = richSafe;
+module.exports.MARK_KEYS = MARK_KEYS;
+module.exports.TEXT_KEYS = TEXT_KEYS;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-charts",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Organized ECharts spec → option builder + React <Chart> for direct Apache ECharts (no wrapper). Premium optimizers plug in at the option level.",
   "main": "index.js",
   "files": [
@@ -33,5 +33,8 @@
   },
   "devDependencies": {
     "echarts": "^6.1.0"
+  },
+  "dependencies": {
+    "@xeplr/rules": "^1.0.0"
   }
 }