@xeplr/ui-charts 1.0.1

package/README.md

@@ -0,0 +1,99 @@
+# @xeplr/ui-charts
+
+Direct **Apache ECharts** in React (no wrapper), driven by an **organized
+ECharts-mirror spec**. A premium optimizer plugs in at the option level.
+
+```
+organized spec → buildOption → EChartsOption → [premium.optimize] → useECharts render
+```
+
+## Usage
+
+Primary component — pass the semantic `ChartOptions` object:
+
+```jsx
+import { XeplrChart } from '@xeplr/ui-charts';
+
+<XeplrChart
+  chartOptions={{
+    data: [{ month: 'Jan', revenue: 18700 }, /* … */],
+    axes: {
+      x: { labels: ['month'], title: { show: true, text: 'Monthly Revenue' } },
+      y: { labels: ['revenue'] }
+    },
+    chartType: 'bar'
+  }}
+  height={360}
+  theme="xeplr-dark"          // brand-neutral default; or "xeplr-light"
+  onWarnings={(w) => console.warn(w)}   // optional; unmapped props reported here
+/>
+```
+
+`XeplrChart` runs `chartOptionsToOption()` internally. Lower-level, the
+ECharts-mirror `<Chart spec={…} />` (backed by `buildOption`) is also exported for
+callers who'd rather author ECharts-shaped specs directly.
+
+## The spec (organized ECharts mirror)
+
+It **is** an ECharts `option`, just organized with sane defaults and two
+conveniences. Anything ECharts accepts flows straight through — that's the escape
+hatch.
+
+- **`data: rows`** → `dataset: { source: rows }`.
+- **`field`-binding** → ECharts `encode`:
+  - `xAxis:{field:'month'}` + `series:[{type:'bar', field:'sales'}]` → `encode:{x:'month',y:'sales'}`
+  - `yAxis:{field}` → horizontal; pie `series:{type:'pie', categoryField, field}` → `encode:{itemName,value}`
+- **Defaults** (spec always wins): grid + `tooltip.trigger:'axis'` for cartesian /
+  `'item'` otherwise, legend when multi-series, animation on.
+- **Meta keys** `renderer` / `theme` are consumed by the renderer, stripped from the option.
+
+`buildOption(spec)` is a pure function — the contract both the renderer and premium
+optimizers operate on.
+
+## Premium seam
+
+`<Chart optimize={fn} />` (or `useECharts(spec, { optimize })`) — `optimize` is a
+pure `(EChartsOption) => EChartsOption` applied right before `setOption`. Premium
+algorithms live in the suite, import nothing from here beyond the option shape, and
+optimize **any** chart (spec-built or raw).
+
+## Theme
+
+This is an **upstream, brand-neutral** package — it ships **no** consumer branding.
+The defaults `xeplr-dark` / `xeplr-light` use the dataviz method's validated
+*reference* palette (blue-led): dark worst-adjacent CVD ΔE 10.3 (floor band), light
+ΔE 24.2. Mark specs (2px lines, ≥8px markers, 4px rounded bars, 2px pie gaps,
+recessive axes) are baked in.
+
+**Consumers supply their own brand theme downstream.** The theme *structure* lives
+here in `makeTheme(palette)`; the brand *values* live in the app:
+
+```js
+import { echarts, makeTheme } from '@xeplr/ui-charts';
+echarts.registerTheme('mybrand-dark', makeTheme({
+  color: ['#c98500', '#3987e5', /* …validated brand hues… */],
+  surface: '#1a1a19', primary: '#fff', secondary: '#c3c2b7',
+  muted: '#898781', gridline: '#2c2c2a', baseline: '#383835'
+}));
+// <Chart theme="mybrand-dark" ... />
+```
+
+## Bundle / registration
+
+`register.js` registers a default module set (bar/line/pie/scatter + grid/tooltip/
+legend/title/dataset/toolbox/dataZoom + canvas & svg). Need more? Register on the
+same instance:
+
+```js
+import { echarts } from '@xeplr/ui-charts';
+import { RadarChart } from 'echarts/charts';
+echarts.use([RadarChart]);
+```
+
+## API
+
+`buildOption(spec)` · `<Chart>` · `useECharts(spec, opts)` · `echarts` (configured) ·
+`themes` (`makeTheme`, `xeplrDark`, `xeplrLight`, `registerThemes`, `palettes`).
+
+`react` and `echarts` are peer deps. `buildOption` + `themes` are pure (no peers) —
+that's what the test suite (`npm test`, 21 tests) covers. Rendering you confirm in-app.

package/index.js

@@ -0,0 +1,38 @@
+// @xeplr/ui-charts — organized ECharts spec → option + React <Chart>, using
+// Apache ECharts DIRECTLY (no wrapper), with a premium optimize() seam.
+//
+//   const { Chart, buildOption } = require('@xeplr/ui-charts');
+//
+//   <Chart spec={{
+//     data: rows,
+//     xAxis: { field: 'month' }, yAxis: { name: 'Sales' },
+//     series: [{ type: 'bar', field: 'sales', name: 'Sales' }]
+//   }} height={360} />
+//
+// Layers:
+//   buildOption(spec) → EChartsOption   (pure; the contract premium optimizes)
+//   useECharts / <Chart>                (React lifecycle bridge)
+//   echarts                             (configured core — register more modules on it)
+//
+// Styling is theme-agnostic here: the resolved theme (@xeplr/ui-utils) arrives as
+// a ChartOptions object and is translated by chartOptionsToOption. No themes here.
+
+module.exports = {
+  // Primary component — pass the semantic ChartOptions object (type.js):
+  //   <XeplrChart chartOptions={chartOptions} />
+  XeplrChart: require('./lib/XeplrChart'),
+
+  // Semantic ChartOptions → ECharts option. Returns
+  // { option, seriesLabel, chartType, warnings }.
+  chartOptionsToOption: require('./lib/chart-options'),
+
+  // Lower-level: organized ECharts-mirror spec path.
+  Chart: require('./lib/Chart'),
+  buildOption: require('./lib/build-option'),
+
+  useECharts: require('./lib/use-echarts'),
+  echarts: require('./lib/register')
+  // Styling is not a ui-charts concern anymore — the resolved theme arrives as a
+  // ChartOptions object (from @xeplr/ui-utils resolveTheme) and is translated by
+  // chartOptionsToOption. No registered ECharts themes / makeTheme here.
+};

package/lib/Chart.js

@@ -0,0 +1,32 @@
+// <Chart /> — declarative wrapper over useECharts for the organized
+// ECharts-mirror spec (see buildOption). For the semantic ChartOptions object,
+// use <XeplrChart>. Plain React.createElement (no JSX) → no build step.
+//
+//   const { Chart } = require('@xeplr/ui-charts');
+//   <Chart spec={spec} height={360} optimize={premium.optimize} />
+
+var React = require('react');
+var useECharts = require('./use-echarts');
+var buildOption = require('./build-option');
+
+function Chart(props) {
+  props = props || {};
+  var option = React.useMemo(function () { return buildOption(props.spec); }, [props.spec]);
+
+  var api = useECharts(option, {
+    theme: props.theme,
+    renderer: props.renderer,
+    optimize: props.optimize,
+    onEvents: props.onEvents,
+    notMerge: props.notMerge
+  });
+
+  var style = Object.assign(
+    { width: '100%', height: props.height != null ? props.height : 320 },
+    props.style
+  );
+
+  return React.createElement('div', { ref: api.containerRef, className: props.className, style: style });
+}
+
+module.exports = Chart;

package/lib/XeplrChart.js

@@ -0,0 +1,66 @@
+// <XeplrChart /> — the primary React component. Takes the semantic ChartOptions
+// object (see type.js), translates it to an ECharts option via
+// chartOptionsToOption, and renders it. Plain React.createElement (no JSX).
+//
+//   const { XeplrChart } = require('@xeplr/ui-charts');
+//   <XeplrChart chartOptions={chartOptions} height={360} />
+//
+// Container frame — width / height / top / left — is read from `chartOptions`
+// (CSS values per the type; numbers → px). These size/position the container
+// div, not the ECharts option, so the translator ignores them. `top`/`left`
+// switch the container to absolute positioning. Matching React props override.
+//
+// Props:
+//   chartOptions   the semantic ChartOptions object            (required)
+//   height/width   number|string — override chartOptions.height/width
+//   theme          optional registered ECharts theme name. Normally unset —
+//                  styling comes from chartOptions (built from the theme).
+//   renderer       'canvas' (default) | 'svg'
+//   optimize       (EChartsOption) => EChartsOption — premium seam
+//   onWarnings     (string[]) => void — receives the translator's warnings.
+//                  If omitted, warnings are console.warn'd unless `silent`.
+//   silent         suppress the default console.warn of warnings
+//   onEvents       { click: fn, ... } ECharts events, bound at init
+//   notMerge       default true (structural replace); false to merge/animate
+//   style, className  passed to the container div
+
+var React = require('react');
+var useECharts = require('./use-echarts');
+var chartOptionsToOption = require('./chart-options');
+var containerStyle = require('./container-style');
+
+function XeplrChart(props) {
+  props = props || {};
+
+  // Translate once per chartOptions change → { option, seriesLabel, chartType, warnings }.
+  var result = React.useMemo(function () {
+    return chartOptionsToOption(props.chartOptions || {});
+  }, [props.chartOptions]);
+
+  // Surface the translator's warnings (unmapped props) — never silently.
+  React.useEffect(function () {
+    var w = result.warnings;
+    if (!w || !w.length) return;
+    if (typeof props.onWarnings === 'function') { props.onWarnings(w); return; }
+    if (!props.silent && typeof console !== 'undefined' && console.warn) {
+      console.warn('[XeplrChart] ' + w.length + ' unmapped chart propert' + (w.length > 1 ? 'ies' : 'y') + ':\n  ' + w.join('\n  '));
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [result]);
+
+  var api = useECharts(result.option, {
+    theme: props.theme,
+    renderer: props.renderer,
+    optimize: props.optimize,
+    onEvents: props.onEvents,
+    notMerge: props.notMerge
+  });
+
+  return React.createElement('div', {
+    ref: api.containerRef,
+    className: props.className,
+    style: containerStyle(props)
+  });
+}
+
+module.exports = XeplrChart;

package/lib/build-option.js

@@ -0,0 +1,111 @@
+// buildOption(spec) — the pure core. Turns the "organized ECharts mirror" spec
+// into a real ECharts `option`. NO echarts/react imports → trivially testable.
+//
+// What it adds over hand-writing raw ECharts option:
+//   1. `data: rows` → `dataset: { source: rows }`.
+//   2. `field`-binding: `xAxis:{field:'month'}` + `series:[{type:'bar', field:'sales'}]`
+//      → ECharts `encode` (dataset dimension mapping), which is fiddly by hand.
+//   3. Sensible structural defaults (grid, tooltip trigger by chart kind, legend
+//      when multi-series, animation) — applied only where the spec is silent.
+//
+// Everything else is passthrough: because the spec is ECharts-shaped, any
+// property you set flows straight through. That's the built-in escape hatch.
+//
+// Theme/color are NOT applied here. This is the raw ECharts-mirror escape hatch:
+// set colors/styling directly in the spec, or feed a themed option via the
+// ChartOptions path (XeplrChart). `renderer`/`theme` meta keys are stripped.
+
+var deepMerge = require('./deep-merge');
+
+var META_KEYS = ['renderer', 'theme'];
+
+function buildOption(spec) {
+  var s = cloneWithout(spec || {}, META_KEYS);
+
+  var hasCartesian = s.xAxis !== undefined || s.yAxis !== undefined;
+
+  // 1. rows → dataset
+  if (Array.isArray(s.data) && s.dataset === undefined) {
+    s.dataset = { source: s.data };
+  }
+  delete s.data;
+
+  // 2. axis field-binding + type defaults
+  var xField = null, yField = null;
+  if (s.xAxis !== undefined) { var rx = normalizeAxis(s.xAxis, 'category'); s.xAxis = rx.axis; xField = rx.field; }
+  if (s.yAxis !== undefined) { var ry = normalizeAxis(s.yAxis, 'value');    s.yAxis = ry.axis; yField = ry.field; }
+
+  // 3. series field-binding
+  var seriesCount = 0;
+  if (s.series !== undefined) {
+    var arr = toArray(s.series).map(function (ser) {
+      return normalizeSeries(ser, { xField: xField, yField: yField });
+    });
+    s.series = arr;
+    seriesCount = arr.length;
+  }
+
+  // 4. structural defaults (spec wins over these)
+  var defaults = structuralDefaults(hasCartesian, seriesCount);
+  return deepMerge(defaults, s);
+}
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function cloneWithout(obj, keys) {
+  var out = {};
+  for (var k in obj) if (keys.indexOf(k) === -1) out[k] = obj[k];
+  return out;
+}
+
+function toArray(v) { return Array.isArray(v) ? v.slice() : [v]; }
+
+// Strip the convenience `field` off an axis, default its `type`. Returns the
+// cleaned axis plus the field name (for series encode). Handles axis arrays.
+function normalizeAxis(axis, defaultType) {
+  if (Array.isArray(axis)) {
+    var field = null;
+    var arr = axis.map(function (a) {
+      var r = normalizeAxis(a, defaultType);
+      if (field === null) field = r.field;
+      return r.axis;
+    });
+    return { axis: arr, field: field };
+  }
+  var a = {};
+  for (var k in axis) if (k !== 'field') a[k] = axis[k];
+  if (a.type === undefined) a.type = defaultType;
+  return { axis: a, field: (axis && axis.field != null) ? axis.field : null };
+}
+
+// Resolve `field` (value dim) + `categoryField`/`nameField` into ECharts encode,
+// unless the caller already supplied an explicit `encode`. Strips the sugar.
+function normalizeSeries(ser, ctx) {
+  var out = {};
+  for (var k in ser) if (k !== 'field' && k !== 'categoryField' && k !== 'nameField') out[k] = ser[k];
+
+  var field = ser.field;
+  var catField = ser.categoryField != null ? ser.categoryField : ser.nameField;
+
+  if (field != null && out.encode === undefined) {
+    if (ctx.xField != null)      out.encode = { x: ctx.xField, y: field };   // vertical cartesian
+    else if (ctx.yField != null) out.encode = { y: ctx.yField, x: field };   // horizontal cartesian
+    else if (catField != null)   out.encode = { itemName: catField, value: field }; // pie/funnel
+    else                         out.encode = { value: field };
+  }
+  return out;
+}
+
+function structuralDefaults(hasCartesian, seriesCount) {
+  var d = { animation: true };
+  if (hasCartesian) {
+    d.grid = { left: '3%', right: '4%', bottom: '3%', top: 48, containLabel: true };
+    d.tooltip = { trigger: 'axis' };
+  } else {
+    d.tooltip = { trigger: 'item' };
+  }
+  if (seriesCount > 1) d.legend = {};   // multi-series → show legend (auto from names)
+  return d;
+}
+
+module.exports = buildOption;

package/lib/chart-options.js

@@ -0,0 +1,353 @@
+// chartOptionsToOption — translate the semantic, CSS-like `ChartOptions` (see
+// type.js) into an ECharts `option`. STYLING/CHROME ONLY for now: title, axes
+// appearance, legend, tooltip, chart area, plus the data-label + chart-type
+// carried out for the (future) series/data layer.
+//
+//   const { option, seriesLabel, chartType, warnings } = chartOptionsToOption(chartOptions);
+//
+// It maps everything with an ECharts equivalent, parses CSS units → ECharts
+// values, and collects `warnings` for properties ECharts can't express (rather
+// than failing). Pure — no echarts/react imports.
+
+function chartOptionsToOption(co, opts) {
+  co = co || {};
+  opts = opts || {};
+  var root = opts.rootFontSize || 16;
+  var warnings = [];
+  var ctx = { root: root, warn: function (m) { warnings.push(m); } };
+
+  var option = {};
+
+  if (co.title) {
+    var t = co.title;
+    if (t.show !== false) {
+      option.title = clean(assign(
+        { text: t.text, show: true, textStyle: fontToTextStyle(t.font, ctx, 'title.font') },
+        positionKeys(resolvePosition(t.positioning, ctx)),
+        styleToEcharts(t.style, ctx, 'title.style'),
+        t.font && t.font.align ? { textAlign: t.font.align } : {}
+      ));
+    } else {
+      option.title = { show: false };
+    }
+  }
+
+  if (co.axes) {
+    if (co.axes.x) option.xAxis = axisToEcharts(co.axes.x, ctx, 'axes.x');
+    if (co.axes.y) option.yAxis = axisToEcharts(co.axes.y, ctx, 'axes.y');
+  }
+
+  if (co.legend) {
+    var lg = co.legend;
+    if (lg.show !== false) {
+      var lgPos = resolvePosition(lg.positioning, ctx);
+      option.legend = clean(assign(
+        {
+          show: true,
+          orient: lgPos._vertical ? 'vertical' : 'horizontal',
+          textStyle: fontToTextStyle(lg.font, ctx, 'legend.font'),
+          itemGap: parseSize(lg.itemGap, ctx)
+        },
+        positionKeys(lgPos),
+        styleToEcharts(lg.style, ctx, 'legend.style')
+      ));
+      if (lg.iconGap != null) ctx.warn('legend.iconGap has no ECharts equivalent (dropped)');
+    } else {
+      option.legend = { show: false };
+    }
+  }
+
+  if (co.tooltip) {
+    var tt = co.tooltip;
+    option.tooltip = clean(assign(
+      { show: tt.show !== false, textStyle: fontToTextStyle(tt.font, ctx, 'tooltip.font'), formatter: tt.formatter },
+      styleToEcharts(tt.style, ctx, 'tooltip.style')
+    ));
+  }
+
+  if (co.chartArea) {
+    var ca = co.chartArea;
+    var grid = {};
+    var edges = edgesFrom(ca.margin, ca.padding, ctx);
+    assign(grid, edges);
+    grid.containLabel = true;
+    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);
+    }
+    if (ca.style && ca.style.background && ca.style.background.image) ctx.warn('chartArea.style.background.image has no ECharts equivalent (dropped)');
+  }
+
+  // dataLabel is per-series in ECharts — resolve it now, apply when series exist.
+  var seriesLabel;
+  if (co.dataLabel) {
+    var dl = co.dataLabel;
+    seriesLabel = clean(assign(
+      {
+        show: dl.show !== false,
+        position: labelPosition(dl.positioning),
+        formatter: dl.formatter
+      },
+      fontToTextStyle(dl.font, ctx, 'dataLabel.font'),
+      styleToEcharts(dl.style, ctx, 'dataLabel.style')
+    ));
+  }
+
+  // ── data + series (field-binding via axes.x/y.labels) ──
+  // x.labels[0] = category dimension; each y.labels entry = one series (value dim).
+  if (Array.isArray(co.data)) option.dataset = { source: co.data };
+
+  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;
+
+  // 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
+      });
+      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' };
+  }
+
+  // ── 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
+  // unnecessary). These are the two fields beyond CSS-chrome that a theme needs.
+  if (Array.isArray(co.palette)) option.color = co.palette;
+  if (co.fontFamily) option.textStyle = assign(option.textStyle || {}, { fontFamily: co.fontFamily });
+
+  return { option: option, seriesLabel: seriesLabel, chartType: co.chartType, warnings: warnings };
+}
+
+// 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).
+function applyMarks(ser, type, m, ctx) {
+  if (!m) return;
+  if (type === 'line') {
+    var ls = clean({ width: parseSize(m.width, ctx) });
+    if (ls) ser.lineStyle = assign(ser.lineStyle || {}, ls);
+    if (m.symbol != null) ser.symbol = m.symbol;
+    if (m.symbolSize != null) ser.symbolSize = m.symbolSize;
+    if (m.smooth != null) ser.smooth = m.smooth;
+  } 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
+      if (m.gap.color != null) bit.borderColor = m.gap.color;
+      if (m.gap.width != null) bit.borderWidth = parseSize(m.gap.width, ctx);
+    }
+    if (Object.keys(bit).length) ser.itemStyle = assign(ser.itemStyle || {}, bit);
+  } else if (type === 'scatter') {
+    if (m.symbolSize != null) ser.symbolSize = m.symbolSize;
+  } else if (type === 'pie') {
+    var pit = {};
+    if (m.border) {
+      if (m.border.color != null) pit.borderColor = m.border.color;
+      if (m.border.width != null) pit.borderWidth = parseSize(m.border.width, ctx);
+    }
+    if (Object.keys(pit).length) ser.itemStyle = assign(ser.itemStyle || {}, pit);
+    if (m.label && m.label.font && m.label.font.color != null) {
+      ser.label = assign(ser.label || {}, { color: m.label.font.color });
+    }
+  }
+}
+
+// ── sub-mappers ──────────────────────────────────────────────────────────
+
+function axisToEcharts(ax, ctx, path) {
+  if (!ax) return undefined;
+  var a = { show: ax.show !== false };
+
+  if (ax.line) {
+    a.axisLine = clean({
+      show: ax.line.show !== false,
+      lineStyle: clean({ color: ax.line.color, width: parseSize(ax.line.width, ctx), type: lineType(ax.line.style) })
+    });
+  }
+  if (ax.grid) {
+    a.splitLine = clean({
+      show: !!ax.grid.show,
+      lineStyle: clean({ color: ax.grid.color, width: parseSize(ax.grid.width, ctx), type: lineType(ax.grid.style) })
+    });
+  }
+  if (ax.ticks) {
+    var tk = ax.ticks;
+    a.axisTick = clean({ show: tk.show !== false, length: parseSize(tk.length, ctx) });
+    a.axisLabel = clean(assign(
+      { show: tk.show !== false, rotate: tk.angle, margin: parseSize(tk.margin, ctx), color: tk.color },
+      fontToTextStyle(tk.font, ctx, path + '.ticks.font')
+    ));
+  }
+  if (ax.title) {
+    a.name = ax.title.text;
+    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);
+  }
+  return clean(a);
+}
+
+function fontToTextStyle(font, ctx, path) {
+  if (!font) return undefined;
+  var ts = {
+    fontFamily: font.family,
+    fontSize: parseSize(font.size, ctx),
+    fontWeight: font.weight,
+    fontStyle: font.style,               // normal|italic|oblique (ECharts supports these)
+    color: applyOpacity(font.color, font.opacity),
+    lineHeight: parseSize(font.lineHeight, ctx),
+    align: font.align
+  };
+  ['letterSpacing', 'transform', 'decoration', 'variant'].forEach(function (k) {
+    if (font[k] != null) ctx.warn(path + '.' + k + ' has no ECharts equivalent (dropped)');
+  });
+  return clean(ts);
+}
+
+function styleToEcharts(style, ctx, path) {
+  if (!style) return undefined;
+  var out = {};
+  if (style.background) {
+    if (style.background.color) out.backgroundColor = applyOpacity(style.background.color, style.background.opacity);
+    if (style.background.image) ctx.warn(path + '.background.image has no ECharts equivalent (dropped)');
+  }
+  if (style.border) {
+    var b = style.border;
+    if (b.color != null) out.borderColor = b.color;
+    if (b.width != null) out.borderWidth = parseSize(b.width, ctx);
+    if (b.radius != null) out.borderRadius = parseSize(b.radius, ctx);
+    if (b.style != null) {
+      if (b.style === 'double') ctx.warn(path + '.border.style "double" has no ECharts equivalent (using solid)');
+      out.borderType = b.style === 'double' ? 'solid' : b.style;
+    }
+  }
+  if (style.shadow) {
+    var sh = style.shadow;
+    if (sh.blur != null) out.shadowBlur = parseSize(sh.blur, ctx);
+    if (sh.color != null) out.shadowColor = sh.color;
+    if (sh.x != null) out.shadowOffsetX = parseSize(sh.x, ctx);
+    if (sh.y != null) out.shadowOffsetY = parseSize(sh.y, ctx);
+    if (sh.spread != null) ctx.warn(path + '.shadow.spread has no ECharts equivalent (dropped)');
+  }
+  if (style.opacity != null) ctx.warn(path + '.opacity on a container has no ECharts equivalent — use a color alpha (dropped)');
+  return clean(out);
+}
+
+// position keyword + margin edges → {left,top,right,bottom} (+ _vertical hint)
+function resolvePosition(p, ctx) {
+  if (!p) return {};
+  var out = {};
+  switch (p.position) {
+    case 'top':    out.top = 0; out.left = 'center'; break;
+    case 'bottom': out.bottom = 0; out.left = 'center'; break;
+    case 'left':   out.left = 0; out.top = 'middle'; out._vertical = true; break;
+    case 'right':  out.right = 0; out.top = 'middle'; out._vertical = true; break;
+    case 'center': out.left = 'center'; out.top = 'middle'; break;
+  }
+  if (p.margin) {
+    if (p.margin.top != null)    out.top = parseSize(p.margin.top, ctx);
+    if (p.margin.right != null)  out.right = parseSize(p.margin.right, ctx);
+    if (p.margin.bottom != null) out.bottom = parseSize(p.margin.bottom, ctx);
+    if (p.margin.left != null)   out.left = parseSize(p.margin.left, ctx);
+  }
+  if (p.align) {
+    if (out._vertical) out.top = p.align === 'start' ? 'top' : p.align === 'end' ? 'bottom' : 'middle';
+    else out.left = p.align === 'start' ? 'left' : p.align === 'end' ? 'right' : 'center';
+  }
+  return out;
+}
+
+function positionKeys(pos) {
+  var out = {};
+  ['left', 'top', 'right', 'bottom'].forEach(function (k) { if (pos[k] !== undefined) out[k] = pos[k]; });
+  return out;
+}
+
+function edgesFrom(margin, padding, ctx) {
+  var out = {};
+  ['top', 'right', 'bottom', 'left'].forEach(function (e) {
+    var m = margin && margin[e] != null ? parseSize(margin[e], ctx) : undefined;
+    var p = padding && padding[e] != null ? parseSize(padding[e], ctx) : undefined;
+    var v = sumSizes(m, p);
+    if (v !== undefined) out[e] = v;
+  });
+  return out;
+}
+
+function labelPosition(positioning) {
+  if (!positioning || !positioning.position) return undefined;
+  return positioning.position === 'center' ? 'inside' : positioning.position;
+}
+
+// ── primitives ───────────────────────────────────────────────────────────
+
+function parseSize(v, ctx) {
+  if (v == null) return undefined;
+  if (typeof v === 'number') return v;
+  var s = String(v).trim();
+  if (s === '' || s === 'auto') return undefined;
+  if (s.charAt(s.length - 1) === '%') return s;          // keep percentage string
+  var m = s.match(/^(-?[\d.]+)(px|rem|em|pt)?$/);
+  if (!m) return undefined;
+  var num = parseFloat(m[1]);
+  var unit = m[2] || 'px';
+  var base = (ctx && ctx.root) || 16;
+  if (unit === 'rem' || unit === 'em') return num * base;
+  if (unit === 'pt') return num * (96 / 72);
+  return num;                                            // px / unitless
+}
+
+function sumSizes(a, b) {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  if (typeof a === 'number' && typeof b === 'number') return a + b;
+  return a;   // can't add a % and a px cleanly — margin wins
+}
+
+function applyOpacity(color, opacity) {
+  if (color == null) return undefined;
+  if (opacity == null) return color;
+  var m6 = /^#([0-9a-f]{6})$/i.exec(color);
+  var m3 = /^#([0-9a-f]{3})$/i.exec(color);
+  var r, g, b;
+  if (m6) { var n = parseInt(m6[1], 16); r = (n >> 16) & 255; g = (n >> 8) & 255; b = n & 255; }
+  else if (m3) { var c = m3[1]; r = parseInt(c[0] + c[0], 16); g = parseInt(c[1] + c[1], 16); b = parseInt(c[2] + c[2], 16); }
+  else return color;
+  return 'rgba(' + r + ',' + g + ',' + b + ',' + opacity + ')';
+}
+
+function lineType(style) {
+  if (style == null) return undefined;
+  return (style === 'solid' || style === 'dashed' || style === 'dotted') ? style : undefined;
+}
+
+function assign(target) {
+  for (var i = 1; i < arguments.length; i++) {
+    var src = arguments[i];
+    if (src) for (var k in src) if (src[k] !== undefined) target[k] = src[k];
+  }
+  return target;
+}
+
+function clean(obj) {
+  if (!obj) return undefined;
+  var out = {}, has = false;
+  for (var k in obj) { if (obj[k] !== undefined) { out[k] = obj[k]; has = true; } }
+  return has ? out : undefined;
+}
+
+module.exports = chartOptionsToOption;

package/lib/container-style.js

@@ -0,0 +1,33 @@
+// Resolve the chart container's CSS frame from chartOptions.{width,height,top,left},
+// overridable by matching React props. These size/position the container div —
+// they are NOT ECharts option properties. `top`/`left` switch to absolute
+// positioning. Pure (no react) → unit-testable.
+//
+//   containerStyle({ chartOptions, width?, height?, top?, left?, style? }) → CSSObject
+
+function containerStyle(props) {
+  props = props || {};
+  var co = props.chartOptions || {};
+
+  var width  = firstDefined(props.width,  co.width,  '100%');
+  var height = firstDefined(props.height, co.height, 320);
+  var top    = firstDefined(props.top,  co.top);
+  var left   = firstDefined(props.left, co.left);
+
+  var style = { width: width, height: height };
+  if (top !== undefined || left !== undefined) {
+    style.position = 'absolute';
+    if (top !== undefined)  style.top = top;
+    if (left !== undefined) style.left = left;
+  }
+  return Object.assign(style, props.style);
+}
+
+function firstDefined() {
+  for (var i = 0; i < arguments.length; i++) {
+    if (arguments[i] !== undefined && arguments[i] !== null) return arguments[i];
+  }
+  return undefined;
+}
+
+module.exports = containerStyle;

package/lib/deep-merge.js

@@ -0,0 +1,26 @@
+// Deep-merge for plain objects only. Arrays and non-plain values are REPLACED
+// (not merged) — so `series: [...]` from the spec overrides wholesale, while
+// nested config objects (grid, tooltip, textStyle, …) merge key-by-key.
+// Right side (override) wins.
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) &&
+    (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+}
+
+function deepMerge(base, override) {
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return override === undefined ? base : override;
+  }
+  var out = {};
+  var k;
+  for (k in base) out[k] = base[k];
+  for (k in override) {
+    if (isPlainObject(out[k]) && isPlainObject(override[k])) out[k] = deepMerge(out[k], override[k]);
+    else out[k] = override[k];
+  }
+  return out;
+}
+
+module.exports = deepMerge;
+module.exports.isPlainObject = isPlainObject;

package/lib/register.js

@@ -0,0 +1,31 @@
+// Configured ECharts core — à-la-carte registration keeps bundles tree-shaken
+// (this is the whole point of using ECharts directly). We register a sensible
+// DEFAULT set so the common charts work out of the box; consumers who need more
+// import the extra modules and call `.use([...])` on this same instance.
+//
+//   const { echarts } = require('@xeplr/ui-charts');
+//   import { RadarChart } from 'echarts/charts';
+//   echarts.use([RadarChart]);   // extend when needed
+
+var echarts = require('echarts/core');
+
+var { BarChart, LineChart, PieChart, ScatterChart } = require('echarts/charts');
+var {
+  GridComponent, TooltipComponent, LegendComponent, TitleComponent,
+  DatasetComponent, ToolboxComponent, DataZoomComponent, MarkLineComponent, MarkPointComponent
+} = require('echarts/components');
+var { CanvasRenderer, SVGRenderer } = require('echarts/renderers');
+
+echarts.use([
+  BarChart, LineChart, PieChart, ScatterChart,
+  GridComponent, TooltipComponent, LegendComponent, TitleComponent,
+  DatasetComponent, ToolboxComponent, DataZoomComponent, MarkLineComponent, MarkPointComponent,
+  CanvasRenderer, SVGRenderer
+]);
+
+// No theme registration: styling flows through the ECharts `option` built from
+// the ChartOptions theme (see @xeplr/ui-utils default.theme.json → chartOptionsToOption),
+// so there's a single source of styling. Register your own theme on this
+// instance only if you specifically want ECharts' theme layer.
+
+module.exports = echarts;

package/lib/use-echarts.js

@@ -0,0 +1,71 @@
+// useECharts — the imperative-lifecycle bridge. Takes an already-built ECharts
+// `option`; the calling component is responsible for producing it (memoized).
+// Init once, setOption on option change, ResizeObserver → resize, dispose on
+// unmount. This is the ~30 lines written once so charts are declarative above.
+//
+//   const option = useMemo(() => buildOption(spec), [spec]);
+//   const { containerRef } = useECharts(option, { theme, optimize });
+//   return <div ref={containerRef} style={{ height: 320 }} />;
+//
+// The premium seam is `optimize`: a pure (option) => option applied right before
+// setOption — so premium algos optimize the FINAL option and work for any chart.
+// theme + renderer are fixed at init (ECharts can't swap them live) — change them
+// by remounting (e.g. a React `key`).
+
+var React = require('react');
+var echarts = require('./register');
+
+function useECharts(option, options) {
+  options = options || {};
+  var containerRef = React.useRef(null);
+  var chartRef = React.useRef(null);
+
+  // No default registered ECharts theme: styling is carried entirely by the
+  // `option` (built from the ChartOptions theme). `theme` stays an optional
+  // escape hatch for anyone who registers + names their own ECharts theme.
+  var theme = options.theme;
+  var renderer = options.renderer || 'canvas';
+
+  React.useEffect(function () {
+    var el = containerRef.current;
+    if (!el) return undefined;
+
+    var chart = echarts.init(el, theme, { renderer: renderer });
+    chartRef.current = chart;
+
+    if (options.onEvents) {
+      Object.keys(options.onEvents).forEach(function (name) {
+        chart.on(name, options.onEvents[name]);
+      });
+    }
+
+    var ro = null;
+    if (typeof ResizeObserver !== 'undefined') {
+      ro = new ResizeObserver(function () { if (chartRef.current) chartRef.current.resize(); });
+      ro.observe(el);
+    }
+
+    return function () {
+      if (ro) ro.disconnect();
+      chart.dispose();
+      chartRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  React.useEffect(function () {
+    var chart = chartRef.current;
+    if (!chart) return;
+    var opt = option || {};
+    if (typeof options.optimize === 'function') opt = options.optimize(opt);
+    chart.setOption(opt, { notMerge: options.notMerge !== false, lazyUpdate: true });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [option, options.optimize]);
+
+  return {
+    containerRef: containerRef,
+    getInstance: function () { return chartRef.current; }
+  };
+}
+
+module.exports = useECharts;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@xeplr/ui-charts",
+  "version": "1.0.1",
+  "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": [
+    "index.js",
+    "lib/"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "peerDependencies": {
+    "echarts": "^5.4.0",
+    "react": ">=17"
+  },
+  "keywords": [
+    "echarts",
+    "charts",
+    "react",
+    "dataviz",
+    "visualization",
+    "xeplr"
+  ],
+  "author": "xeplr",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Xeplr/xeplr-ui-charts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "echarts": "^6.1.0"
+  }
+}