@pepperui/charts 1.1.0

package/src/echarts.js

@@ -0,0 +1,344 @@
+/* ============================================================================
+   ECharts — the Pepper theme and the option builder (SVG renderer).
+
+   `echartsTheme(accent, canvas)` is the payload for `echarts.registerTheme`: the
+   defaults a chart written by hand still picks up. `buildOption(cfg, box)` is the
+   whole house chart — the shape Paggy's decks, the editor's preview and the PPTX
+   exporter all agree on — built from the same THEME.
+
+   Charts are static (`animation:false`) so the SVG output is clean vector.
+   ============================================================================ */
+
+/** The colour of series `i`: the dataset's own `color` wins, then the accent's
+ *  palette. */
+function palette(accent, series, i, count) {
+  return (series && series.color) || seriesColor(THEME, accent, i, count);
+}
+
+/** The ECharts theme object — `echarts.registerTheme('pepper-blue', echartsTheme('blue'))`.
+ *  Everything `buildOption` sets explicitly is set here too, so a chart written
+ *  by hand against the theme looks like a chart the builder made. */
+function echartsTheme(accent, canvas) {
+  const t = chartText(canvas);
+  const text = { color: THEME.ink, fontFamily: THEME.font, fontSize: t.size };
+  return {
+    color: (THEME.series[accent] || THEME.series.blue).slice(),
+    backgroundColor: 'transparent',
+    animation: false,
+    textStyle: text,
+    legend: {
+      icon: 'circle',
+      itemWidth: GEOMETRY.legend.itemWidth,
+      itemHeight: GEOMETRY.legend.itemHeight,
+      itemGap: GEOMETRY.legend.itemGap,
+      textStyle: text,
+    },
+    // RULE 1 — the baseline is the CATEGORY axis' own line: the foot of a column
+    // chart, the left edge of a ranked one. `chart/rest` at 2px, heavier than the
+    // grid. RULE 2 — the grid keeps a line at every tick, on the value axis.
+    categoryAxis: {
+      axisLine: { show: true, lineStyle: { color: THEME.rest, width: GEOMETRY.axis.baselineWidth } },
+      axisTick: { show: false },
+      splitLine: { show: false },
+      axisLabel: text,
+    },
+    valueAxis: {
+      axisLine: { show: false },
+      axisTick: { show: false },
+      splitLine: { lineStyle: { color: THEME.grid, width: GEOMETRY.axis.gridWidth } },
+      axisLabel: text,
+    },
+    bar: { itemStyle: { borderRadius: barRadius(false) }, barMaxWidth: GEOMETRY.bar.maxWidth },
+    // RULE 5 — a dot at every point; stated rather than left to the ECharts default
+    line: { smooth: true, showSymbol: true, symbolSize: GEOMETRY.line.symbolSize, lineStyle: { width: GEOMETRY.line.width } },
+    pie: {
+      radius: [GEOMETRY.donut.radiusInner, GEOMETRY.donut.radiusOuter],
+      itemStyle: { borderColor: THEME.onFill, borderWidth: GEOMETRY.donut.segmentBorder },
+    },
+  };
+}
+
+/* ---------- bar / column / line ---------- */
+function axisChart(cfg) {
+  const t = chartText(cfg.canvas);
+  const textStyle = (size) => ({ color: THEME.ink, fontFamily: THEME.font, fontSize: size || t.size });
+  const horizontal = cfg.index_axis === 'y' || cfg.type === 'hbar';
+  // an area and a sparkline are lines with a fill and, in the sparkline's case,
+  // nothing else drawn — they are chart types the recipes have always shown and
+  // the builder never had (D9)
+  const isArea = cfg.type === 'area' || cfg.type === 'sparkline';
+  const isLine = cfg.type === 'line' || isArea;
+  const spark = cfg.type === 'sparkline';
+  // axis labels and data labels share ONE formatter (cfg.value_format is the
+  // legacy per-label override) — the compact style needs every value to pick
+  // its magnitude, so the numbers are gathered before the axis is built
+  const allVals = (cfg.datasets || []).flatMap((d) => d.data || []).filter((v) => typeof v === 'number');
+  const valFmt = valueFormatter((cfg.axis && cfg.axis.fmt) || cfg.fmt,
+                                (cfg.axis && cfg.axis.format) || cfg.format, allVals);
+  const labFmt = cfg.value_format ? formatter(cfg.value_format) : valFmt;
+
+  const series = (cfg.datasets || []).map((d, i) => {
+    const color = palette(cfg.accent, d, i, (cfg.datasets || []).length);   // RULE 12 needs the count
+    const s = {
+      name: d.label || `Series ${i + 1}`,
+      type: isLine ? 'line' : 'bar',
+      data: d.data,
+      color,
+      label: {
+        show: cfg.data_labels !== false && !isLine,
+        position: cfg.label_inside === 'middle' ? 'inside' : (cfg.label_inside ? 'insideTop' : (horizontal ? 'right' : 'top')),
+        formatter: (p) => labFmt(p.value),
+        ...textStyle(),
+        ...(cfg.label_inside ? { color: cfg.label_color || labelInk(THEME, color) } : {}),
+      },
+    };
+    if (!isLine) {
+      s.barMaxWidth = cfg.bar_max || GEOMETRY.bar.maxWidth;
+      s.itemStyle = { color, borderRadius: barRadius(horizontal, undefined, cfg.radius_all) };
+      if (d.stack || cfg.stacked) {
+        s.stack = d.stack || 'total';
+        // RULE 4 — the TOP segment rounds, the joints stay square. Every segment
+        // used to be square, top included, which is the mark he made on the audit
+        // (*"where rounded corners?"*, D3). The last series of a stack is its top.
+        const last = i === (cfg.datasets || []).length - 1;
+        s.itemStyle.borderRadius = barRadius(horizontal, last ? 'last' : 'mid', cfg.radius_all);
+        s.label.position = 'inside';
+        s.label.formatter = d.pct_label ? (p) => p.value ? labFmt(p.value) : '' : s.label.formatter;
+        if (d.pct_color) s.label.color = d.pct_color;
+      }
+    } else {
+      s.smooth = cfg.smooth !== false;
+      s.lineStyle = { width: GEOMETRY.line.width, color };
+      // RULE 5 — a dot at every point. An area's own line carries none: the
+      // pictures rules 10 and 11 were picked on were drawn that way, and a
+      // forecast series says so for itself (`d.forecast`).
+      s.showSymbol = !isArea && cfg.dots !== false;
+      s.symbolSize = GEOMETRY.line.symbolSize;
+      s.label.show = cfg.data_labels === true;
+      if (isArea) {
+        // RULE 10 — the band is the series colour at 12 %
+        s.areaStyle = { color, opacity: cfg.area_opacity != null ? cfg.area_opacity : GEOMETRY.area.opacity };
+      }
+      if (d.forecast) {
+        // RULE 11 — the dashed forecast line is `chart/4`, 3px, 6 on 6 off. Its
+        // 1.68 : 1 on the 12 % band is a stated exemption, his pick, recorded in
+        // the contrast matrix.
+        const fc = seriesColor(THEME, cfg.accent, 3);   // `chart/4` of this accent
+        s.lineStyle = { width: GEOMETRY.area.forecast.width, color: fc, type: GEOMETRY.area.forecast.dash };
+        s.itemStyle = { color: fc };
+        s.areaStyle = undefined;
+        s.showSymbol = false;
+      }
+      if (spark) { s.showSymbol = false; s.label.show = false; }
+    }
+    return s;
+  });
+
+  // RULE 9 — a ONE-SERIES chart has three treatments and all three are correct:
+  // one flat colour (the default in an accent mode), the accent's own tints, and
+  // multicolor. `barColors` is the one place the per-bar cycle lives, so Chart.js
+  // and the site read the same function instead of writing their own (D17). A
+  // caller names the treatment with `cfg.treatment`; `accent: 'multicolor'`
+  // cycles without being asked, because that palette exists to be cycled and a
+  // single-colour reading of it paints every bar red. Lines stay one colour (one
+  // line cannot cycle); multi-series charts keep their per-series hues.
+  if (series.length === 1 && !isLine && (cfg.treatment || cfg.accent === 'multicolor')) {
+    const bars = barColors(THEME, cfg.accent, (cfg.labels || cfg.datasets[0].data || []).length, cfg.treatment);
+    series[0].itemStyle.color = (p) => bars[p.dataIndex % bars.length];
+  }
+
+  const catAxis = {
+    type: 'category',
+    data: cfg.labels || [],
+    // RULE 1 — the baseline: `chart/rest` at 2px, the line the bars stand on
+    axisLine: { show: true, lineStyle: { color: THEME.rest, width: GEOMETRY.axis.baselineWidth } },
+    axisTick: { show: false },
+    // RULE 6 — largest first. ECharts runs a y category axis bottom-up, so a
+    // ranked chart has been shipping upside down (D13); `inverse` puts row 0 at
+    // the top, which is where the deck and Figma already read it.
+    inverse: cfg.inverse != null ? cfg.inverse : (horizontal && RANKED_TOP_FIRST),
+    axisLabel: {
+      ...textStyle(cfg.category_size || t.size),
+      rotate: cfg.category_rotation || 0,
+      interval: 0,
+      // RULE 7 — measured, not reserved: no width is held for the row name, and
+      // `containLabel` fits the grid round whatever it measures. A caller that
+      // must truncate a very long name passes `label_width` itself (D6).
+      ...(horizontal && cfg.label_width ? { width: cfg.label_width, overflow: 'truncate' } : {}),
+    },
+  };
+  // tight-band data (uptime 99.92-99.99 on a 0-100 axis) renders as identical
+  // full bars — the narrow-band floor lifts the axis so the variation is visible
+  // (rules.js, stress-test S04); an explicit cfg.axis.min always wins.
+  const autoMin = narrowBandFloor(allVals);
+  const valAxis = {
+    type: 'value',
+    min: (cfg.axis && cfg.axis.min) != null ? cfg.axis.min : autoMin,
+    max: cfg.axis && cfg.axis.max,
+    interval: cfg.axis && cfg.axis.interval,
+    // RULE 2 — a line at every tick, behind the bars
+    splitLine: { show: cfg.grid !== false, lineStyle: { color: THEME.grid, width: GEOMETRY.axis.gridWidth } },
+    axisLine: { show: false },
+    axisLabel: { ...textStyle(), formatter: (v) => valFmt(v) },
+  };
+
+  if (spark) {
+    // a sparkline is the line and nothing else: no axis, no grid, no labels
+    catAxis.show = false; valAxis.show = false;
+    catAxis.axisLine = { show: false }; catAxis.axisLabel = { show: false };
+    valAxis.splitLine = { show: false }; valAxis.axisLabel = { show: false };
+  }
+
+  return {
+    animation: false,
+    grid: spark ? { left: 0, right: 0, top: 2, bottom: 2 } : {
+      left: GEOMETRY.grid.left,
+      right: cfg.grid_right != null ? cfg.grid_right : GEOMETRY.grid.right,
+      top: cfg.grid_top != null ? cfg.grid_top
+        : ((cfg.datasets || []).length > 1 ? GEOMETRY.grid.topWithLegend : GEOMETRY.grid.top),
+      bottom: cfg.grid_bottom != null ? cfg.grid_bottom : GEOMETRY.grid.bottom,
+      containLabel: true,
+    },
+    legend: legendBlock(cfg, !spark && (cfg.datasets || []).length > 1 && cfg.legend !== false, textStyle),
+    xAxis: horizontal ? valAxis : catAxis,
+    yAxis: horizontal ? catAxis : valAxis,
+    series,
+    textStyle: textStyle(),
+  };
+}
+
+/** The top-right legend: circular markers, 10px, 18 apart. */
+function legendBlock(cfg, show, textStyle) {
+  if (cfg.legend === true) show = true;  // skill parity: legend even for one series
+  if (show === false) return { show: false };
+  return {
+    show: true, top: 0, right: 0, icon: 'circle',
+    itemWidth: GEOMETRY.legend.itemWidth,
+    itemHeight: GEOMETRY.legend.itemHeight,
+    itemGap: GEOMETRY.legend.itemGap,
+    textStyle: textStyle(),
+  };
+}
+
+/* ---------- donut (pie is retired) ---------- */
+function pieChart(cfg, box) {
+  const t = chartText(cfg.canvas);
+  const textStyle = (size) => ({ color: THEME.ink, fontFamily: THEME.font, fontSize: size || t.size });
+  const D = GEOMETRY.donut;
+  // Pie is retired: every circular chart IS the house donut. Configs written
+  // before the write-path normalizers existed (or by anything that slips past
+  // them) arrive UNSTYLED — carrying none of the house flags — and used to
+  // render as a default-ECharts pie/donut with callout labels. Restyle those
+  // to the donut_compare spec here, at render time, so that look can never
+  // ship. Designed donut layouts and editor-converted donuts always carry at
+  // least one of the flags below and pass through untouched.
+  if (cfg.type === 'pie') cfg.type = 'donut';
+  if (!cfg.data && cfg.datasets && cfg.datasets[0])
+    cfg.data = cfg.datasets[0].data || [];
+  if (cfg.legend_pct == null && cfg.labels_on == null
+      && cfg.legend == null && cfg.cutout == null) {
+    cfg.labels_on = GEOMETRY.donut.labelsOn;
+    cfg.seg_border = D.unstyled.segmentBorder;
+    cfg.cutout = D.unstyled.cutout;
+    cfg.bg = cfg.bg || THEME.page;
+    cfg.legend_pct = D.unstyled.legendPct;
+  }
+  // TWO-slice donuts read as share-vs-rest (Fedor 2026-08-12): slice 1 keeps
+  // the accent's MAIN color, slice 2 is always chart/rest — never the accent's
+  // readable mid tint (that rule stands for every OTHER chart, incl. 3+ slice
+  // donuts). Assigned per slice right here so ECharts can never cycle past it;
+  // an explicit cfg.colors (kpi_donuts rings, designed layouts) still wins.
+  // PPTX mirrors in pptx_export.chart. See rules.js sliceColor.
+  const data = (cfg.labels || []).map((l, i) => ({
+    name: l,
+    value: (cfg.data || [])[i],
+    itemStyle: { color: sliceColor(THEME, cfg.accent, cfg.labels, i, cfg.colors) },
+  }));
+  // a donut has no axis block, so its format lives at the top level (the axis
+  // fallback only catches a config that came from an axis chart type-switch)
+  const fmtSrc = cfg.fmt || (cfg.axis && cfg.axis.fmt);
+  const fmt = valueFormatter(fmtSrc, cfg.format, cfg.data || []);
+  const total = (cfg.data || []).reduce((a, b) => a + (+b || 0), 0);
+  const noLegend = cfg.legend === false;
+  const ringLabels = cfg.labels_on != null ? cfg.labels_on : (noLegend ? true : GEOMETRY.donut.labelsOn);
+  const pctName = (name) => {
+    const i = (cfg.labels || []).indexOf(name);
+    const v = +((cfg.data || [])[i]) || 0;
+    return total ? name + ' — ' + Math.round(v / total * 100) + '%' : name;
+  };
+  // House composition for editor-converted donuts (legend_pct): a padded ring
+  // with the legend right beside it, the pair centred as ONE group in the box
+  // (the donut_compare look). Computed in px from the real element size, so a
+  // wide chart panel can't strand the legend at the far edge or blow the ring
+  // up to full height. Designed donut layouts (no legend_pct) are untouched.
+  let group = null;
+  if (cfg.legend_pct && cfg.legend !== false && box && box.w > 40 && box.h > 40) {
+    const R = Math.round(D.groupRingShare * Math.min(box.w, box.h) / 2);
+    const inner = Math.round(R * ((cfg.cutout || D.cutout) / 100));
+    // estimate the legend block width from the ACTUAL entries (20px Poppins ≈
+    // 10.5px/char + dot/gap) — a fixed guess skews the centring when labels are
+    // short ("Jan — 7%") or long ("PHL — Philippines — 14.3%")
+    // D16 — his mark, *"be carefull with layout becose mobuppsX numer on the right
+    // is cut out"*. The width used to be GUESSED at 10.5px a character and only
+    // the LEFT edge was clamped, so an entry wider than the guess ran off the
+    // right. Measured now, and clamped at both edges: when the group cannot fit,
+    // the ring gives way, not the text.
+    const wide = (cfg.labels || []).map(pctName)
+      .reduce((m, str) => Math.max(m, textWidth(str, D.groupLegend.fontSize)), 0);
+    const legendW = Math.min(D.groupLegendMax, wide + D.groupLegendPad);
+    const gap = D.groupGap;
+    const free = box.w - legendW - gap - 2 * D.groupEdgeMin;
+    const r = Math.max(8, Math.min(R, Math.round(free / 2)));
+    const inner2 = Math.round(r * ((cfg.cutout || D.cutout) / 100));
+    const left = Math.max(D.groupEdgeMin, Math.round((box.w - (2 * r + gap + legendW)) / 2));
+    group = { R: r, inner: inner2, cx: left + r, legendLeft: left + 2 * r + gap };
+  }
+  return {
+    animation: false,
+    // bg: the editor's type-switch sets the page white so a converted donut sits
+    // on white (designed donut layouts leave it unset — transparent, card decides)
+    ...(cfg.bg ? { backgroundColor: cfg.bg } : {}),
+    legend: cfg.legend === false ? { show: false } : (group ? {
+      orient: 'vertical', left: group.legendLeft, top: 'middle', icon: 'circle',
+      itemWidth: D.groupLegend.itemWidth, itemHeight: D.groupLegend.itemHeight,
+      itemGap: D.groupLegend.itemGap, textStyle: textStyle(D.groupLegend.fontSize),
+      formatter: pctName,
+    } : {
+      orient: 'vertical', right: 0, top: 'middle', icon: 'circle',
+      itemWidth: D.legend.itemWidth, itemHeight: D.legend.itemHeight,
+      itemGap: D.legend.itemGap, textStyle: textStyle(D.legend.fontSize),
+      // RULE 8 — the legend is where the share is written, so it carries it by
+      // default; `legend_pct: false` is how a caller whose labels already say the
+      // share (a designed donut layout) turns the suffix off.
+      ...(cfg.legend_pct !== false ? { formatter: pctName } : {}),
+    }),
+    series: [{
+      type: 'pie',
+      radius: group ? [group.inner, group.R]
+                    : (cfg.cutout ? [cfg.cutout + '%', '100%'] : [D.radiusInner, D.radiusOuter]),
+      center: group ? [group.cx, '50%']
+                    : (cfg.legend === false ? ['50%', '50%'] : ['38%', '50%']),
+      data,
+      // RULE 8 — the share is written in the LEGEND only and the ring stays
+      // clean. Outside labels used to be ON unless a caller turned them off, so a
+      // composed donut printed every share twice and ran leader lines out of the
+      // box (D15). The exception is a donut with NO legend to write into: the
+      // share goes back on the ring rather than nowhere.
+      label: ringLabels ? {
+        show: true,
+        formatter: (p) => (fmtSrc || cfg.format) ? fmt(p.value) : p.percent.toFixed(0) + '%',
+        ...textStyle(), fontWeight: THEME.weightStrong,
+        position: 'outside',
+      } : { show: false },
+      labelLine: { show: ringLabels },
+      itemStyle: { borderColor: THEME.onFill, borderWidth: cfg.seg_border != null ? cfg.seg_border : D.segmentBorder },
+    }],
+  };
+}
+
+/** The whole option for one chart config. `box` is the element's current pixel
+ *  size and is only read by the composed donut. */
+function buildOption(cfg, box) {
+  if (cfg.type === 'pie' || cfg.type === 'donut') return pieChart(cfg, box);
+  return axisChart(cfg);
+}

package/src/format.js

@@ -0,0 +1,119 @@
+/* ============================================================================
+   format — the number-format OBJECT and the legacy readers.
+
+   DL-10 names this as part of the package because three renderers have to agree
+   on it: the ECharts option below, Chart.js (3.1.2) and `pptx_export.py`, which
+   mirrors the same resolution order and the same compact magnitude as an Excel
+   number-format code. Moved here from Paggy's `charts.js` unchanged — the comments
+   are its own, and every one of them records a bug this code is the fix for.
+   ============================================================================ */
+
+/* ---------- the legacy strings, kept forever as READERS ----------
+   Retired as PRODUCED (Fedor 2026-08-14): nothing mints a `currency_*` any more,
+   because a dollar sign baked into the renderer shipped dollar labels on a euro
+   column. A deck built before the format object still has to render the way it
+   was drawn, so the readers stay. */
+function fmtCurrencyM(v) {
+  if (v == null) return '';
+  const n = Number(v);
+  if (Math.abs(n) >= 1e6) return '$' + (n / 1e6).toFixed(2).replace(/\.?0+$/, '') + 'M';
+  if (Math.abs(n) >= 1e3) return '$' + Math.round(n / 1e3) + 'K';
+  return '$' + n;
+}
+function fmtCurrencyK(v) {
+  if (v == null) return '';
+  const n = Number(v);
+  if (Math.abs(n) >= 1e3) {
+    const k = n / 1e3;
+    // sub-10K keeps decimals so $1,000 / $1,040 / $1,215 don't ALL collapse
+    // to "$1K" (stress-test T04, 2026-07-09)
+    const s = Math.abs(k) < 10 ? k.toFixed(2).replace(/\.?0+$/, '')
+                               : Math.round(k).toLocaleString('en-US');
+    return '$' + s + 'K';
+  }
+  return '$' + n;
+}
+function fmtPlain(v) { return v == null ? '' : Number(v).toLocaleString('en-US'); }
+function fmtPercent(v) { return v == null ? '' : Number(v).toLocaleString('en-US') + '%'; }
+
+function formatter(kind) {
+  switch (kind) {
+    case 'currency_M': return fmtCurrencyM;
+    case 'currency_K': return fmtCurrencyK;
+    case 'percent': return fmtPercent;
+    default: return fmtPlain;
+  }
+}
+
+/* ---------- the number FORMAT object (Fedor 2026-08-14) ----------
+   The old $K/$M pills baked a DOLLAR sign into the renderer, so a euro column
+   shipped dollar labels ("what if the user has euros, K euros, millions or
+   pounds?"). The format is currency-neutral instead: a style, a VERBATIM
+   prefix/suffix and an optional decimals override.
+     fmt = { style: auto|group|group2|compact, prefix, suffix, decimals }
+     auto    today's plain number      group   1,000        (0 decimals)
+     group2  1,000.00 (2 decimals)     compact 1.2K / 1.2M  (1 decimal)
+     decimals: null = follow the style, otherwise 0..4 and it wins
+   prefix/suffix are cosmetic TEXT, never a unit conversion. */
+// PER VALUE, not one unit for the whole chart (Fedor 2026-08-14). A shared
+// magnitude turns 820,000 into "$0.8M" and 310,000 into "$0.3M" — a lost
+// significant digit and a label nobody writes by hand. The retired
+// currency_K/currency_M readers always shortened per value ($820K beside
+// $1.04M) and that is the look every existing deck has; `compact` is their
+// currency-NEUTRAL twin, so it must shorten the same way. Verified against
+// the T04_table_kpis golden, which is exactly this chart.
+function compactUnit(v) {
+  const m = Math.abs(Number(v) || 0);
+  if (m >= 1e6) return { div: 1e6, tag: 'M' };
+  if (m >= 1e3) return { div: 1e3, tag: 'K' };
+  return { div: 1, tag: '' };
+}
+
+function fmtObject(f, vals) {
+  const style = f.style || 'auto';
+  const pre = f.prefix == null ? '' : String(f.prefix);
+  const suf = f.suffix == null ? '' : String(f.suffix);
+  const dec = (f.decimals == null || f.decimals === '')
+    ? null : Math.max(0, Math.min(4, Math.round(Number(f.decimals)) || 0));
+  const compact = style === 'compact';
+  return function (v) {
+    if (v == null || v === '') return '';
+    let n = Number(v);
+    if (!isFinite(n)) return '';
+    let d = dec;
+    let unit = compact ? compactUnit(n) : null;
+    // 3 significant digits is what the retired currency readers actually did
+    // ($820K, $1.04M, $1.22K) — a fixed decimal count cannot do both, and it
+    // is the rule that keeps a shortened label as informative as the number.
+    if (unit) {
+      // ...but the rounding can push a value INTO the next band: 999.5 with
+      // 0 decimals prints "1,000" while 1000 prints "1K", so two bars a half
+      // apart would wear different units. Re-pick the unit from the ROUNDED
+      // value (once is enough — 999.5 → 1000 → K → 1.0 is already stable).
+      const dOf = (x) => Math.max(0, 3 - String(Math.floor(Math.abs(x))).length);
+      if (dec == null) {
+        const r = Math.round(Math.abs(n / unit.div) * 10 ** dOf(n / unit.div)) /
+                  10 ** dOf(n / unit.div);
+        if (r >= 1000) unit = compactUnit(Math.sign(n) * r * unit.div);
+      }
+      n = n / unit.div;
+      if (d == null) d = dOf(n);
+    } else if (d == null && style === 'group') d = 0;
+    else if (d == null && style === 'group2') d = 2;
+    let s = d == null ? n.toLocaleString('en-US')
+      : n.toLocaleString('en-US', { minimumFractionDigits: d, maximumFractionDigits: d });
+    // "2.0K"/"1.00M" read as 2K/1M — but a decimals setting typed by hand
+    // is honoured exactly as typed
+    if (unit) s = (dec == null ? s.replace(/\.(\d*?)0+$/, (m, k) => (k ? '.' + k : '')) : s) + unit.tag;
+    return pre + s + suf;
+  };
+}
+
+/* THE resolution order (locked with the panel, 2026-08-14): the fmt object if
+   the chart carries one → else its legacy string → else plain. Nothing ever
+   silently repaints a deck built before the panel existed. Shared with the
+   editor's chart modal (its live preview IS this function). */
+function valueFormatter(fmt, legacy, vals) {
+  if (fmt && typeof fmt === 'object') return fmtObject(fmt, vals);
+  return formatter(legacy || 'plain');
+}

package/src/index.js

@@ -0,0 +1,28 @@
+/** @pepperui/charts — the source parts, in order.
+ *
+ *  `build/charts.js` concatenates these into `dist/pepper-charts.js` (a classic script that
+ *  defines `window.PepperCharts`, so a bundler-free page — Paggy, the quarter builder, a Blade
+ *  view — needs no tooling) and `dist/pepper-charts.mjs` (the ES module), with the GENERATED
+ *  theme (`dist/theme.json`, an output of `npm run build` from `tokens/*.json`) injected ahead
+ *  of them as `THEME`.
+ *
+ *  The parts share ONE scope. They are not standalone modules and they do not import each
+ *  other — this file is the order, exactly the way `packages/css/src/index.css` is the order
+ *  of the stylesheet's parts. Nothing here holds a colour: every value the charts paint with
+ *  comes from `THEME`, and `THEME` comes from the token source.
+ */
+export const parts = [
+  // the number-format object and the legacy readers — shared with pptx_export.py (DL-10)
+  'format.js',
+  // the house rules that are not colour: the narrow-band axis floor, the two-slice donut,
+  // and the chart-recipe geometry the Figma page draws
+  'rules.js',
+  // the ECharts theme and option builder
+  'echarts.js',
+  // the Chart.js theme — the same values, the pieces that renderer composes with
+  'chartjs.js',
+  // the optional DOM adapter: mount every [data-chart] in a root and keep it fitted
+  'mount.js',
+  // the public object
+  'api.js',
+];

package/src/mount.js

@@ -0,0 +1,71 @@
+/* ============================================================================
+   mount — the optional DOM adapter.
+
+   A page marks a chart with `class="echart" data-chart` and puts its config in a
+   child `<script type="application/json">`; the accent comes from the nearest
+   `[data-accent]` ancestor, which is the same attribute `tokens.css` switches the
+   accent modes on. Nothing here is required to use the theme — a React or Vue
+   consumer calls `buildOption` itself — but the two hard-won behaviours below are
+   worth carrying rather than rediscovering.
+   ============================================================================ */
+
+/** Re-fit every chart in `root` to its container's CURRENT size, rebuilding the
+ *  px-composed donuts (their ring and legend are laid out from the real box). */
+function refit(root) {
+  (root || document).querySelectorAll('.echart[data-chart]').forEach((el) => {
+    if (!el.__chart) return;
+    el.__chart.resize();
+    if (el.__cfg && el.__cfg.legend_pct) {
+      el.__chart.setOption(buildOption(el.__cfg, { w: el.clientWidth, h: el.clientHeight }));
+    }
+  });
+}
+
+/** Render every `[data-chart]` element inside `root`. */
+function renderAll(root) {
+  const nodes = (root || document).querySelectorAll('.echart[data-chart]');
+  nodes.forEach((el) => {
+    const src = el.querySelector('script[type="application/json"]');
+    if (!src) return;
+    let cfg;
+    try { cfg = JSON.parse(src.textContent); } catch (e) { console.error('chart json', e); return; }
+    const slideEl = el.closest('[data-accent]');
+    cfg.accent = cfg.accent || (slideEl ? slideEl.getAttribute('data-accent') : 'blue');
+    if (el.__ro) { el.__ro.disconnect(); el.__ro = null; }
+    if (el.__chart) { el.__chart.dispose(); }
+    const chart = echarts.init(el, null, { renderer: 'svg' });
+    chart.setOption(buildOption(cfg, { w: el.clientWidth, h: el.clientHeight }));
+    el.__chart = chart;
+    el.__cfg = cfg;   // kept for live re-layout while the host card is resized
+    // Keep the chart fitted to its container WHENEVER the container changes size —
+    // font load, a caption growing as the user types, a card resize. ECharts otherwise
+    // keeps its initial SVG size and the plot overlaps the caption until something else
+    // forces a rescale (Fedor 2026-07-14: "the same bug, it goes to normal only if I
+    // click layout mode"). The echart is position:absolute inset:0, so resizing it never
+    // changes its own box → no loop.
+    if (window.ResizeObserver) {
+      let raf = 0;
+      const ro = new ResizeObserver(() => {
+        if (raf) return;
+        raf = requestAnimationFrame(() => {
+          raf = 0;
+          if (!el.__chart) return;
+          el.__chart.resize();
+          if (el.__cfg && el.__cfg.legend_pct) {
+            el.__chart.setOption(buildOption(el.__cfg, { w: el.clientWidth, h: el.clientHeight }));
+          }
+        });
+      });
+      ro.observe(el);
+      el.__ro = ro;
+    }
+  });
+  // The house readiness flag: a print or export path waits on it before it shoots
+  // the page, because an unfinished chart exports as an empty box.
+  window.__chartsReady = true;
+  // Belt-and-suspenders for the initial paint / no-ResizeObserver: re-fit once
+  // webfonts settle (a caption reflows to its real height on font swap).
+  if (document.fonts && document.fonts.ready) {
+    document.fonts.ready.then(() => refit(root));
+  }
+}