@pepperui/charts 1.1.0

package/src/rules.js

@@ -0,0 +1,306 @@
+/* ============================================================================
+   rules — the house chart rules that are not colour, and the recipe geometry.
+
+   Every number here is drawn on the Figma page `Chart recipes` (281:2) and every
+   one of them is a decision with a date. They live in one place so the ECharts
+   builder below, Chart.js (3.1.2) and the PPTX exporter (3.1.3) cannot drift
+   apart the way the palettes did (G13).
+
+   THE HOUSE CHART STANDARD (3.8.1, 2026-09-21; rule 12 added 2026-09-21 on his review of
+   the built result). Twelve rules decided on rendered
+   pairs — `artifacts/requests/2026-09-21-chart-standard/decide.html`, his picks in
+   `answers.json`, the spec in `STANDARD.md`. They are stated here, once, because
+   the audit that found them (3.8.0) found that a picture fixed on its own comes
+   back: the missing baseline was not a slip in one page, it was this file and the
+   two renderers saying `axisLine: { show: false }` three times over.
+
+     1  a column stands on a baseline, heavier than the grid   `axis.baseline`
+     2  a line at every tick, behind the bars                   `axis.grid`
+     3  a column is rounded on top, square at the foot          `bar.radius`
+     4  a stacked column rounds its TOP SEGMENT only            `barRadius()`
+     5  a line carries a dot at every point                     `line.symbolSize`
+     6  a ranked list reads largest first                       `RANKED_TOP_FIRST`
+     7  the row-name lane is measured, not reserved             `category`
+     8  a donut writes its share in the legend only             `donut.labelsOn`
+     9  a one-series chart has THREE treatments, all documented `barColors()`
+    10  the forecast area is the accent at 12 %                 `area.opacity`
+    11  the dashed forecast line is `chart/4`                   `area.forecast`
+    12  a TWO-series chart is `chart/1` against `chart/rest`    `seriesColor()`
+
+   Rule 11 is a stated exemption: `chart/4` on the 12 % accent reads 1.68 : 1,
+   under the 3.0 : 1 floor a meaningful graphical line is held to. He was shown
+   the three readings and picked it; `docs/contrast-matrix.md` carries the pair
+   with his decision beside it, the way D110's twelve kept pairs are.
+   ============================================================================ */
+
+/** The chart-recipe geometry. Names are the recipe's, values are the ones the
+ *  plots on `Chart recipes` were drawn at. */
+const GEOMETRY = {
+  // RULES 1 and 2 — the lines of a plot. A column stands on a baseline drawn in
+  // `chart/rest` at 2px, heavier than the grid behind it, and the grid keeps a
+  // line at every tick. The baseline belongs to the CATEGORY axis: the foot of a
+  // column chart, the left edge of a ranked one — in both it is the line the bars
+  // stand on. The value axis draws none.
+  axis: {
+    baselineWidth: 2,
+    gridWidth: 1,
+  },
+  bar: {
+    // RULE 3 — 4px on the top corners only, square at the foot, in BOTH renderers.
+    // The foot used to be rounded too on the Chart.js side, on the reasoning that
+    // a fully rounded column would not look like it needed a baseline; it now has
+    // one, so the shape follows the baseline back (D2, `chartjs.js` drops
+    // `borderSkipped: false`).
+    // RULE 4 — a stacked column rounds the TOP of its LAST segment and nothing
+    // else: the joints stay square, because a rounded joint draws a gap that is
+    // not in the data. See `barRadius()`.
+    radius: 4,
+    maxWidth: 96,
+  },
+  line: {
+    // RULE 5 — a 4px spline with a dot at every point. This reverses what this
+    // file said until 2026-09-21 (*no dots — the dot lane is for end markers
+    // only*): one renderer obeyed the written rule and the other did not, and he
+    // picked the dots on the pair (D14).
+    width: 4,
+    symbolSize: 9,
+  },
+  // RULES 10 and 11 — an area (the forecast band) is its series colour at 12 %,
+  // and the dashed line over it is `chart/4` at 3px, 6 on 6 off. The fill used to
+  // render black at 22 % in Figma because a bound paint carried `#000000` as its
+  // written colour (D4); the opacity is his pick from the three rendered bands.
+  // The line on an area carries no dots — the pictures rules 10 and 11 were
+  // picked on were drawn that way.
+  area: {
+    opacity: 0.12,
+    forecast: { width: 3, dash: [6, 6] },
+  },
+  legend: {
+    // circular markers, top-right, 18 apart. The Figma page draws the gap at
+    // `space/16` and states the 2px difference rather than moving the code.
+    itemWidth: 10,
+    itemHeight: 10,
+    itemGap: 18,
+  },
+  grid: {
+    // the plot's padding inside its box; `top` leaves the label lane above the
+    // tallest column (26), and twice that when a legend sits above it (44)
+    left: 8,
+    right: 40,
+    topWithLegend: 44,
+    top: 26,
+    bottom: 4,
+  },
+  category: {
+    // RULE 7 — the row-name lane is MEASURED, not reserved. 200px used to be held
+    // for the name however short the names were, which left the wide empty block
+    // on the left of every ranked card (D6). Nothing is reserved now: the lane is
+    // as wide as the longest name and `containLabel` fits the grid round it. A
+    // caller that must truncate passes `label_width` itself.
+    labelGap: 12,
+  },
+  donut: {
+    // RULE 8 — a donut writes its share in the LEGEND ONLY; 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 its leader lines out of the box
+    // (D15). The one exception is a donut with no legend to write into
+    // (`legend: false`, the KPI progress rings): the share goes back on the ring,
+    // because the alternative is a chart that states its number nowhere.
+    labelsOn: false,
+    // the ring: 72% cutout, 3px borders in the on-fill white, slices in the
+    // accent's series order
+    cutout: 72,
+    segmentBorder: 3,
+    radiusInner: '58%',
+    radiusOuter: '85%',
+    // the composed "ring beside its legend" block (donut_compare): the ring takes
+    // 62% of the shorter side, the legend is measured from its real entries at
+    // ~10.5px a character, and the pair is centred as ONE group
+    groupRingShare: 0.62,
+    groupGap: 56,
+    groupLegendMax: 380,
+    // the fallback when there is no canvas to measure with: Poppins' average
+    // advance is about 0.55 of the size. `textWidth()` measures the real string
+    // whenever it can — the estimate at 10.5px a character is what cut
+    // "MobuppsX — 14%" off the right edge of his donut (D16)
+    groupLegendCharRatio: 0.55,
+    groupLegendPad: 34,
+    groupEdgeMin: 24,
+    groupLegend: { itemWidth: 16, itemHeight: 16, itemGap: 22, fontSize: 20 },
+    legend: { itemWidth: 14, itemHeight: 14, itemGap: 16, fontSize: 16 },
+    // a config that reaches the renderer carrying none of the house flags is
+    // restyled to this rather than shipping as a default-ECharts pie
+    // labels come from `labelsOn` above — the standard, not a second copy of it
+    unstyled: { cutout: 70, segmentBorder: 0, legendPct: true },
+  },
+};
+
+/** The canvas a chart is drawn on decides its text size: 15 on a slide, 12 on
+ *  web (`type/<canvas>/label/medium`, D36). Slide is the default because the first
+ *  consumer is a 1920x1080 deck, and an unknown canvas is a slide rather than an
+ *  error — a chart with no text is worse than a chart with slide-sized text.
+ *  Shared by both renderers. */
+function chartText(canvas) {
+  return THEME.text[canvas] || THEME.text.slide;
+}
+
+/** Series `i` of `accent`, cycling. The palettes are monochromatic per accent —
+ *  the accent's own tints — except `multicolor`, which is distinct hues; either
+ *  way the cycle repeats when a chart has more series than the palette has
+ *  entries. An unknown accent falls back to blue, the default mode.
+ *
+ *  Every value comes from `THEME.series`, which is generated from
+ *  `accent/<mode>/chart/1–5` — no palette is typed by hand here or anywhere else
+ *  (G13, DL-10). */
+function seriesColor(theme, accent, i, count) {
+  // RULE 12 — a chart with exactly TWO series is a comparison, and a comparison reads as one thing
+  // against the rest of it: series 1 keeps the accent's `chart/1` and series 2 is `chart/rest`, never
+  // the accent's second tint. This is the two-slice donut rule (Fedor 2026-08-12) generalised to every
+  // chart, at his word on 2026-09-21: *"when you're using two two color charts, so we can use this
+  // gray as the second color… the same way a two-coloured donut chart uses"*. `count` is how many
+  // series the chart has; a caller that does not know it gets the plain palette.
+  if (count === 2 && i === 1) return theme.rest;
+  const base = theme.series[accent] || theme.series.blue;
+  return base[i % base.length];
+}
+
+/** RULE 9 — the colours of a ONE-SERIES chart. Three treatments, all correct,
+ *  all documented (Fedor 2026-09-21: *"you have multicolor, you have one color,
+ *  and you have color with different tints. All these three options are
+ *  correct"*). The design system's job is to make all three available and to show
+ *  all three, not to pick one.
+ *
+ *    'flat'        every bar in the accent's `chart/1` — the default in an accent
+ *                  mode, which is what "a chart follows the accent of the slide"
+ *                  means, and what the system already did
+ *    'tints'       the accent's own chart/1–5, cycling — for a comparison across
+ *                  the bars
+ *    'multicolor'  the red→yellow→blue→gray cycle, hand-set and never automatic
+ *                  (`docs/DESIGN_SYSTEM.md:35`, quoted in STANDARD.md)
+ *
+ *  `accent: 'multicolor'` cycles by default: that palette exists to be cycled, and
+ *  a single-colour reading of it paints every bar red, which is the deck bug
+ *  (D17). This function is the ONE place the cycle lives — ECharts had it and
+ *  Chart.js did not, so the site wrote its own (`docs_gen.py`).
+ *
+ *  @returns {string[]} one colour per bar, `n` long
+ */
+function barColors(theme, accent, n, treatment) {
+  const how = treatment || (accent === 'multicolor' ? 'multicolor' : 'flat');
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    if (how === 'flat') out.push(seriesColor(theme, accent, 0));
+    else if (how === 'multicolor') out.push(seriesColor(theme, 'multicolor', i));
+    else out.push(seriesColor(theme, accent, i));
+  }
+  return out;
+}
+
+/** RULES 3 and 4 — the corner radii of one bar, as the four-corner array both
+ *  renderers take. `horizontal` rotates the rounded pair to the bar's end;
+ *  `stack` is undefined for an unstacked bar, `'last'` for the top segment of a
+ *  stack and `'mid'` for every segment below it.
+ *
+ *  The foot of a column is square in every case: it stands on the baseline. */
+function barRadius(horizontal, stack, all) {
+  const r = GEOMETRY.bar.radius;
+  if (all) return r;
+  if (stack === 'mid') return 0;
+  return horizontal ? [0, r, r, 0] : [r, r, 0, 0];
+}
+
+/** RULE 6 — a ranked list reads largest first: the first row of the data sits at
+ *  the TOP. ECharts runs a y category axis bottom-up, so a horizontal chart needs
+ *  `inverse: true` and has been shipping upside down without it (D13). Chart.js
+ *  and Figma already read top-down, which is why only one renderer was wrong. */
+const RANKED_TOP_FIRST = true;
+
+/** A hex colour at `alpha`, as `rgba()`. RULE 10's band is a colour AT an
+ *  opacity, and the two renderers say that differently — ECharts takes an
+ *  `areaStyle.opacity`, Chart.js takes one colour value — so the conversion lives
+ *  here rather than in either of them. A colour that is not a plain `#rrggbb`
+ *  (already rgba, a CSS name) is returned untouched. */
+function withAlpha(hex, alpha) {
+  const m = /^#([0-9a-f]{6})$/i.exec(String(hex || '').trim());
+  if (!m) return hex;
+  const n = parseInt(m[1], 16);
+  return 'rgba(' + ((n >> 16) & 255) + ',' + ((n >> 8) & 255) + ',' + (n & 255) + ',' + alpha + ')';
+}
+
+/** The rendered width of a string in the chart's own type, in px.
+ *
+ *  RULES 7 and D16 both come from a width that was guessed rather than measured:
+ *  200px reserved for a row name, 10.5px assumed for a character of a legend
+ *  entry — his donut cut "MobuppsX" off the right edge. Measured with a canvas
+ *  when there is a document to make one in (every browser channel), and estimated
+ *  from `groupLegendCharRatio` when there is not (a Node render, a test). */
+let measureCtx;
+function textWidth(text, size, weight) {
+  const str = String(text == null ? '' : text);
+  if (typeof document !== 'undefined' && document.createElement) {
+    try {
+      measureCtx = measureCtx || document.createElement('canvas').getContext('2d');
+      measureCtx.font = (weight ? weight + ' ' : '') + size + 'px ' + THEME.font;
+      const w = measureCtx.measureText(str).width;
+      if (w > 0) return Math.ceil(w);
+    } catch (e) { /* no canvas here — fall through to the estimate */ }
+  }
+  return Math.ceil(str.length * size * GEOMETRY.donut.groupLegendCharRatio);
+}
+
+/** The ink of a label written INSIDE a fill (D110, 2026-09-17).
+ *
+ *  The fill decides it. On an accent's main colour the label takes that accent's
+ *  own `on-accent` — near-black on yellow, white on blue and red — and because the
+ *  rule is keyed by the fill and not by the mode, multicolor's yellow series flips
+ *  with it. On any other fill the label stays `onFill`. A white label on
+ *  yellow/400 read 1.62 : 1; yellow's own ink reads 12.65.
+ *
+ *  Both sides come from `THEME.labelOn`, generated from `accent/<mode>/chart/1`
+ *  and `accent/<mode>/on-accent`. A caller's explicit `label_color` still wins. */
+function labelInk(theme, fill) {
+  const f = typeof fill === 'string' ? fill.toLowerCase() : '';
+  for (const accent of Object.keys(theme.labelOn)) {
+    if (theme.labelOn[accent].fill.toLowerCase() === f) return theme.labelOn[accent].ink;
+  }
+  return theme.onFill;
+}
+
+/** The narrow-band axis floor (stress-test S04, 2026-07-09).
+ *
+ *  Tight-band data — uptime 99.92–99.99 on a 0–100 axis — renders as identical
+ *  full bars. When every value sits in a narrow high band, lift the axis floor so
+ *  the variation is visible. Mixed-sign data is left alone, and an explicit
+ *  `axis.min` always wins (the caller applies that, not this).
+ *
+ *  @param {number[]} values every numeric value in the chart
+ *  @returns {number|undefined} the floor, or undefined when the rule does not apply
+ */
+function narrowBandFloor(values) {
+  if (!values || values.length <= 1) return undefined;
+  const lo = Math.min(...values);
+  const hi = Math.max(...values);
+  if (!(lo > 0 && hi > 0 && (hi - lo) / hi < 0.05)) return undefined;
+  const pad = (hi - lo) || hi * 0.01;
+  return Math.max(0, Math.floor((lo - pad) * 100) / 100);
+}
+
+/** The two-slice donut rule (Fedor 2026-08-12).
+ *
+ *  A donut with exactly TWO slices reads as share-vs-rest: slice 1 keeps the
+ *  accent's main colour and slice 2 is always `chart/rest` — never the accent's
+ *  readable mid tint, which is the rule for every OTHER chart including 3+ slice
+ *  donuts. An explicit `colors` on the config still wins (the kpi_donuts progress
+ *  rings, the designed layouts). `pptx_export.chart` mirrors it per point.
+ */
+function isTwoSlice(labels) {
+  return (labels || []).length === 2;
+}
+
+/** The colour of slice `i` of a donut, with the two-slice rule applied.
+ *  `explicit` is the config's own `colors` array and always wins. */
+function sliceColor(theme, accent, labels, i, explicit) {
+  if (explicit && explicit[i]) return explicit[i];
+  if (isTwoSlice(labels) && i === 1) return theme.rest;
+  return seriesColor(theme, accent, i);
+}