@pepperui/charts 1.1.0

package/README.md

@@ -0,0 +1,117 @@
+# @pepperui/charts
+
+**One palette, four renderers.** The Mobupps design system's chart theme: the per-accent series
+palettes, the two-slice donut rule, the narrow-band axis floor and the shared number-format object —
+all generated from `tokens/*.json`, so no chart palette is typed by hand anywhere (**DL-10**, closes
+**G13**).
+
+Before this package the same colours were mirrored in three places by hand: Paggy's `charts.js`,
+the quarter builder's `pptx_export.py` and the dashboard skill's `chart-recipes.md`. Three copies of
+a number is three chances to drift, and they had drifted.
+
+## What is in it
+
+| Path | What it is |
+|---|---|
+| `dist/theme.json` | **generated** by `npm run build` — every colour a chart paints with, and the token path each one came from (`$sources`) |
+| `dist/pepper-charts.js` | the browser build: one `<script>` tag, defines `window.PepperCharts`, mounts every `[data-chart]` on load |
+| `dist/pepper-charts.mjs` | the same code as an ES module, side-effect free |
+| `src/format.js` | the number-format object (`{style, prefix, suffix, decimals}`) and the retired legacy readers |
+| `src/rules.js` | the palette lookup, the narrow-band floor, the two-slice donut, the recipe geometry |
+| `src/echarts.js` | `echartsTheme()` (a `registerTheme` payload) and `buildOption()` (the whole house chart) |
+| `src/mount.js` | the optional DOM adapter — `renderAll` / `refit`, with the ResizeObserver refit |
+| `src/api.js` | the public object |
+
+`src/index.js` is the order the parts are concatenated in; they share one scope and are not
+standalone modules — `build/charts.js` is the whole build and it is 80 lines of `readFileSync`.
+
+## Install
+
+```sh
+npm install @pepperui/charts
+```
+
+**On npm from 1.1.0** (item 1.2.3). It carries the palette, not the renderer: bring your own ECharts or
+Chart.js. A version on the registry is always a version this repository tags — `charts-v1.1.0` — and never one
+without (`RELEASING.md` §1).
+
+```js
+import { buildOption, echartsTheme, valueFormatter } from '@pepperui/charts';
+```
+
+```html
+<script src="node_modules/@pepperui/charts/dist/pepper-charts.js"></script>
+```
+
+## Use it
+
+```html
+<script src="…/echarts.min.js"></script>
+<script src="…/pepper-charts.js"></script>
+
+<div class="echart" data-chart style="position:relative;width:760px;height:380px">
+  <script type="application/json">
+    {"type":"bar","labels":["Jan","Feb","Mar"],
+     "datasets":[{"label":"Revenue","data":[820000,1044000,310500]}],
+     "axis":{"fmt":{"style":"compact","prefix":"$"}}}
+  </script>
+</div>
+```
+
+The accent comes from the nearest `[data-accent]` ancestor — the same attribute `@pepperui/tokens`
+switches its accent modes on — so **the mode recolours a chart** and nothing else has to change.
+Without one it is `blue`.
+
+```js
+import { buildOption, echartsTheme, valueFormatter } from '@pepperui/charts';
+
+echarts.registerTheme('pepper-red', echartsTheme('red'));      // defaults for a hand-written chart
+chart.setOption(buildOption(cfg, { w: el.clientWidth, h: el.clientHeight }));
+```
+
+## The rules it carries, and where they came from
+
+- **The series palettes are monochromatic per accent** — the accent's own tints — and every accent's
+  **second series is a readable MID tint**, never a pale one: pale tints vanish on the grey chart card
+  (stress-tests T03 / S03, 2026-07-09). Yellow's second series is grey for the same reason. Multicolor
+  is distinct hues instead: red → yellow → blue → grey, and past five series it continues with the same
+  hues one tint lighter. Source: `accent/<mode>/chart/1–5`.
+- **A donut with exactly two slices reads as share-vs-rest** (Fedor, 2026-08-12): slice 1 keeps the
+  accent's main colour, slice 2 is always `chart/rest`. Three or more slices use the normal palette.
+  An explicit `colors` always wins.
+- **The narrow-band axis floor**: when every value sits in a narrow high band (spread under 5% of the
+  maximum — uptime 99.92–99.99 on a 0–100 axis) the value axis lifts just below the band, so the
+  variation is visible instead of five identical full bars (stress-test S04). An explicit `axis.min`
+  wins; mixed-sign data is left alone.
+- **The number format is an object, currency-neutral** (Fedor, 2026-08-14): a style, a *verbatim*
+  prefix and suffix, and an optional decimals override — because a dollar sign baked into a renderer
+  ships dollar labels on a euro column. `compact` picks its magnitude **per value** at three
+  significant digits, so `$820K` sits beside `$1.04M`. The retired `currency_M` / `currency_K` /
+  `percent` / `plain` strings stay forever as *readers*, so a deck built before the panel existed is
+  never silently repainted.
+- **Pie is retired.** Every circular chart is the house donut; a config that arrives carrying none of
+  the house flags is restyled at render time rather than shipping as a default-ECharts pie.
+- **Charts are static** (`animation: false`) so the SVG output is clean vector for PDF and PPTX.
+
+The geometry — 4px column tops and none when stacked, 4px splines with no dots, 10px circular legend
+markers 18 apart, the 72% donut cutout with 3px `chart/on-fill` borders — is in `src/rules.js` under
+`GEOMETRY`, and is drawn on the Figma page **Chart recipes** (`281:2`).
+
+## The theme is the tokens
+
+`dist/theme.json` carries a `$sources` map: `"series.yellow.1": "accent.yellow.chart.2"`, and so on
+for all 32 values. `npm test` reads every one of them back out of `packages/tokens/dist/tokens.css` —
+a different output of the same source, so the two cannot drift together — and fails if any value is
+not what its token says. It also fails if a colour is typed anywhere in `src/`, which is the JS twin
+of the stylelint rule on `@pepperui/css`.
+
+To change a chart colour, change the token and run `npm run build`. Never edit `dist/`.
+
+## Consumers
+
+| Consumer | How it takes the theme |
+|---|---|
+| **Paggy** (slides, ECharts) | `app/static/js/charts.js` **is** `dist/pepper-charts.js` — 3.1.1, delivered, 141/141 slides and 54/54 gallery plots pixel-identical |
+| **the quarter builder** (Chart.js) | 3.1.2 |
+| **`pptx_export.py`** | reads `pepper_tokens.py` — 3.1.3 |
+| **the Figma chart recipes** | cite the same numbers — 3.1.4 |