@micha.bigler/ui-core-micha 3.2.0 → 3.3.0

package/work-orders/UCM-CHART-16.md

@@ -0,0 +1,169 @@
+# UCM-CHART-16 — The x-axis band starves MUI's tick-fit check, and two consumers have patched around it
+
+## Part A — Envelope
+
+*Authored by the Expertenchat. Authoritative WHAT/WHY.*
+
+### Goal
+
+A chart with an axis title **and** horizontal tick labels renders its tick labels. No consumer needs
+to set `xAxis[].height` by hand to make that happen.
+
+### The defect
+
+When the x-axis stays horizontal, `resolveXAxisGeometry` reserves one combined band from
+`TICK_BAND_BASE_PX` + `AXIS_TITLE_BAND_PX`. Once an axis title is also taken from that budget, MUI's
+own internal fit check (`shortenLabels`, against `tickLabelsMaxHeight`) is left **just under one line
+of 12 px text** — so it fails for **every** tick and blanks **every** label, regardless of content.
+
+The signature is distinctive and easy to misread: correctly positioned tick marks, zero non-empty
+label texts. It looks like a data or formatter problem and is neither.
+
+### The evidence: two consumers, same workaround, same magic number
+
+In hram, independently, in two different work orders:
+
+```
+StructuralReachabilityPanel.jsx:386   height: 56      (HRAM-RES-32)
+AccessGapScatterPanel.jsx:212         height: 56      (HRAM-RES-39)
+```
+
+`HRAM-RES-32`'s own comment already diagnosed it correctly and called it what it is — *"a
+pre-existing, latent **shared-core** near-miss"* — then patched locally, because a shared-core fix was
+outside that WO. `HRAM-RES-39` hit the identical wall, read the MUI source, arrived at the same
+cause and the same 56, and patched locally again.
+
+Two things follow. **The third chart with a titled horizontal axis will hit it too**, and its author
+will have to rediscover both the cause and the number. And the package is violating its own stated
+rule: `chartDefaults.js` says *"Rule 1: nothing outside the resolver does chart arithmetic"* — a
+caller hand-computing an axis height is exactly that, now in two places.
+
+### A third occurrence — and it proves scope item 2
+
+Reported by the operator on 2026-08-25, hram's `AccessibilityPanel` in its
+`Urban/Peri-urban/Rural × Division` mode: five band categories, five rendered bar groups, **no tick
+labels at all**. Same signature — positioned ticks, blank text.
+
+This one is different in a way that matters. That chart has **no `xAxisLabel`**
+(`AccessibilityPanel.jsx:164-178`), so the axis title is *not* competing for the band. What it does
+have is `tickLabelStyle: { fontSize: 13 }` — one pixel above the 12 px the base band was sized
+against.
+
+**So the trigger is not "a title takes the room". It is that the band is a near-miss at all**, and
+anything that consumes a little more — a title, a slightly larger font, presumably a taller line
+height — pushes it over. A fixed `height: 56` patched into a third consumer would work at 13 px and
+fail at 14. That is precisely why scope item 2 requires the resolver to **derive** the requirement
+from the tick font size it already knows, rather than adopting the constant two consumers measured
+empirically at 12 px.
+
+(Signature-matched, not yet instrumented — confirm the mechanism on this third case as part of the
+work, since it is the one that distinguishes a derived fix from a bigger constant.)
+
+### Scope
+
+1. **Fix the reservation in the resolver.** The band must leave MUI's fit check room for one full
+   line of tick text *after* the axis title's share, not just under it. The near-miss is small, which
+   is why it went unnoticed — the fix is a correction to the arithmetic, not a redesign.
+2. **Derive it, do not add a second magic number.** 56 is what two consumers measured empirically
+   against a 12 px font; the resolver knows the tick font size and the title band, so it can compute
+   the requirement instead of hard-coding a constant that will be wrong at a different font size.
+3. **Say what changed and why in the comment**, in the style the file already uses — this is the
+   third time this arithmetic has been reasoned about and the first time it is written down where it
+   belongs.
+
+### Non-goals / do not touch
+
+- The rotated-tick path (`xLabels: "angled"`, `spaceForRotatedTicks`). The defect is specific to the
+  horizontal case; a rotated axis reserves its own projected band and is unaffected.
+- `CHART_SIZE_SPACING_UNITS` and the size scale — `UCM-CHART-15`, done.
+- `ChartFrame`, margins, the legend band, `resolveChartLayout`'s other outputs.
+- The consuming panels. Removing hram's two workarounds is `HRAM-CHT-6`, after this ships.
+
+### Risks
+
+- **A mocked prop-assertion test cannot catch this.** The file already records the same trap for a
+  neighbouring bug: *"a mocked prop-assertion test cannot catch this, it only reproduces on an actual
+  MUI scale computation"*. A test that asserts the computed band's number would pass whatever the
+  number is. The test has to observe **rendered label text**, or it is decoration — see test 1.
+- **Raising the band changes every titled-horizontal-axis chart's plot area** by the difference. Small,
+  but it is a visual change to consumers, and it lands on top of `UCM-CHART-15`'s 80 px shift.
+- Fixing it too generously wastes vertical space on every chart. The margin of the near-miss is the
+  budget; do not round it up "to be safe".
+
+### Tests to write
+
+1. **A rendered test**: a chart with an axis title and horizontal ticks produces **non-empty** tick
+   label texts. Written so it fails against the current resolver — a blank-label render is the
+   defect, so the test must be able to see blankness.
+2. The rotated path is unchanged — same band as before for `xLabels: "angled"`.
+3. An axis **without** a title still reserves only the tick band (Rule 2: a band that is not needed
+   collapses to zero).
+
+---
+
+## Part B — Implementation map
+
+`.claude/models.local.json` has no local override, so the default applies: `implementation.runtime`
+is `claude`/`sonnet` — the Orchestrator implemented directly, no Codex dispatch.
+
+**The defect could not be diagnosed from source reading alone** (see Risk section: "a mocked
+prop-assertion test cannot catch this"). MUI's internal fit check (`shortenLabels`, weighed
+against `tickLabelsMaxHeight`, in `node_modules/@mui/x-charts/ChartsXAxis/ChartsSingleXAxisTicks.mjs`
+and `shortenLabels.mjs`) depends on `getBBox`, which jsdom does not implement — so the mechanism
+was confirmed and the fix calibrated against a REAL browser render, not derived from reading MUI's
+source alone:
+
+- `dev/entries.jsx`'s dev harness (`vite`, real Chrome via the internal preview browser) was used
+  to dynamically render the actual, unmocked `BarChart` with a titled horizontal axis under this
+  package's own `createAppTheme`/DM Sans default. Confirmed the defect reproduces exactly as
+  described (blank tick labels, correctly positioned) and does NOT reproduce under MUI's default
+  Roboto stack (real glyph metrics run ~1.3-1.36× fontSize for DM Sans vs ~1.06-1.17× for Roboto —
+  explains why the defect is font-dependent and was missed until a consumer used a taller font).
+- Binary-searched the real, minimal `xAxis[].height` needed to stop blanking, at tick font sizes
+  11-18px, with and without a title (ten measured thresholds total). The result matched
+  `ceil(fontSize * 1.3) + 9` (no title) / `+ 11` (with title, i.e. the same plus 2px) almost
+  exactly — over by at most 1px, never under, across all ten points. `9` corresponds to MUI's own
+  `tickSize`(6, default) + `TICK_LABEL_GAP`(3) internal overhead
+  (`ChartsXAxis/utilities.mjs`/`ChartsSingleXAxisTicks.mjs`); the extra `+2` when a title is
+  present was constant across every font size tested, independent of font.
+- The fix (`resolveXAxisGeometry`'s `angle === 0` branch, `chartDefaults.js`) was re-verified
+  against the SAME real-browser harness after implementing, confirming both reproduced scenarios
+  (title + default font; no title + `tickLabelStyle.fontSize: 13`, the `AccessibilityPanel`
+  signature) now render correctly with no explicit `height` override needed.
+
+Context package: `chartDefaults.js:322-341` (`TICK_BAND_BASE_PX`/`AXIS_TITLE_BAND_PX`/new
+constants), `:366-430ish` (`resolveXAxisGeometry`, the `angle === 0` early-return that was the
+defect site), `:450-475` (`resolveChartLayout`'s `xAxisBand`/`xTitleBand` composition, unchanged).
+Non-goal boundary respected: the `angle !== 0` (rotated) branch below the fixed code is untouched.
+
+---
+
+## Part C — Orchestrator only
+
+> **STOP — everything below addresses the Orchestrator.**
+
+**Tier 3 · tests: the three cases above, at least one of them rendered**
+
+Shared-core, by the tiering table regardless of diff size.
+
+- `reviewer` — the arithmetic, and above all whether test 1 can actually fail.
+- `ui_reviewer` — the plot-area change this causes across consumers.
+- `sec_reviewer` — not run; no auth, data or exposure surface.
+
+### Release
+
+Patch or minor per the repo's convention — this repairs existing behaviour rather than adding
+capability, so **patch** unless the plot-area change is judged large enough to warrant a minor. State
+which and why in the CHANGELOG; `UCM-CHART-15`'s entry is the model for describing a visual
+consequence plainly.
+
+### Register
+
+Row `UCM-CHART-16`, both review notes, the published version, landing SHA(s) in a second commit
+before the push. Record that the fix arrived **third** — two consumers patched around it first — so
+the cost of leaving a shared-core near-miss to consumers is on the record.
+
+### Log
+
+- **2026-08-25** — Envelope authored after `HRAM-RES-39` hit the same defect `HRAM-RES-32` had
+  already diagnosed as shared-core, and applied the identical `height: 56` workaround independently.

package/work-orders/UCM-CHART-17.md

@@ -0,0 +1,195 @@
+# UCM-CHART-17 — The two export buttons make two different promises; make them keep them
+
+## Part A — Envelope
+
+*Authored by the Expertenchat. Authoritative WHAT/WHY.*
+
+### Goal
+
+**Export SVG** yields the chart as scalable, correctly styled vector art. **Export PNG** yields what
+the user is looking at — legend, size key and footnotes included.
+
+### The defect, from the source
+
+`exportChart.js:7-11` clones the first `<svg>` in the container and serialises it raw:
+
+```js
+const svg = findSvg(chartContainer).cloneNode(true);
+svg.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
+return new Blob([new XMLSerializer().serializeToString(svg)], …)
+```
+
+Three consequences, and they compound:
+
+1. **No styles are carried.** MUI X-Charts styles nearly everything through emotion CSS classes —
+   tick fonts and sizes, axis and grid colours, text fill, the theme's typography. The clone keeps
+   `class="MuiChartsAxis-tickLabel css-1abc"` and none of the rules behind it, so a standalone
+   viewer applies bare SVG defaults. This is the "graphically massively different" the operator
+   reported. **The PNG inherits it**, because it rasterises the same blob.
+
+2. **The legend is gone, and that is ours.** `findSvg` takes the *first* `<svg>`, i.e. the chart.
+   Since `HRAM-RES-39`/`HRAM-VIS-2`, consuming panels hide MUI's own legend and render a hand-built
+   one as **HTML** beside the chart, with the size key as a *second* SVG. Both sit outside the
+   exported element. **Before that consolidation, MUI's legend was inside the chart SVG and did get
+   exported** — unstyled, but present. Fixing a legend overlap silently degraded the export, and
+   nobody noticed because nobody opened an exported file.
+
+3. **"The first SVG" is fragile** regardless — a panel that renders any SVG ahead of the chart
+   exports the wrong element. It works today by accident of ordering.
+
+### The decision: two paths, two meanings
+
+The operator chose option C on 2026-08-25. The two buttons already promise different things and
+should stop pretending to be one mechanism:
+
+- **SVG — the chart, faithfully styled.** Keep the clone-and-serialise path, but **inline computed
+  styles onto the cloned nodes** before serialising. Stays true vector: scalable, editable in
+  Illustrator/Inkscape, chart only. It does **not** gain the legend, and that is correct for what
+  this format is for.
+- **PNG — the container, as seen.** Rasterise the whole `chartRef` node rather than the chart SVG, so
+  legend, size key and footnotes are in the file and the output matches the screen by construction.
+
+**Make the difference legible to the user, not only to us.** Two buttons that produce visibly
+different content need labels or tooltips saying so; today they read as one thing in two formats.
+
+### Scope
+
+**`src/components/charts/exportChart.js`**
+
+1. **Inline computed styles** into the SVG clone before serialisation. Walk the clone against the
+   live tree and write the resolved properties as inline style. Keep it to the properties that matter
+   for chart rendering rather than dumping every computed property — a full dump produces enormous
+   files and is its own defect.
+2. **Rasterise the container for PNG.** The `chartRef` node ChartFrame already passes
+   (`ChartFrame.jsx:138`) is the right root — it holds the chart plus everything the panel renders
+   beside it.
+3. **Stop relying on "the first SVG"** for the SVG path — take the chart deliberately, not
+   positionally.
+4. **Preserve the public signatures.** `exportChartSvg(container, filename)` and
+   `exportChartPng(container, filename, backgroundColour)` are consumed by `ChartFrame` and possibly
+   directly; the change is what they produce, not how they are called.
+
+**`src/components/charts/ChartFrame.jsx`** — labels or tooltips that distinguish the two outputs.
+Translated via the existing `chartsTranslations` path, not hard-coded.
+
+### Non-goals / do not touch
+
+- The chart presets, `resolveChartLayout`, the size scale, the axis bands.
+- Consuming apps. hram's six panels with `exportOptions` gain the fix through the pin bump; that is
+  a separate row.
+- Adding export to panels that do not have it (`HRAM-RES-43` did that for one panel in hram).
+
+### Risks
+
+- **A rasteriser is a new dependency in shared-core**, and this package currently has exactly one
+  runtime dependency (`@fontsource/dm-sans`). Adding a second is a real decision — check whether the
+  job can be done with the platform's own APIs first, and if a library is warranted, say why in the
+  WO's implementation record rather than just installing one.
+- **Canvas tainting.** DOM-to-canvas rasterisation routes through an SVG `foreignObject`; any
+  external image or font reference taints the canvas and `toBlob` throws. The existing PNG path
+  already has this exposure and may already be failing on it — worth checking before assuming the new
+  path introduces it.
+- **Fonts in the SVG.** Inlining computed styles records `font-family: "DM Sans"`, which a machine
+  without that font will substitute. Either embed the font or accept the substitution — but decide it
+  and write it down, because a silently substituted font is exactly the "looks different" complaint
+  this WO is fixing.
+- **Style inlining can bloat.** See scope item 1.
+- **This has no test that can see it.** A unit test can assert that a `style` attribute exists; it
+  cannot see that the file looks right. See verification.
+
+### Verification
+
+**Open the exported files.** That is the whole gate, and its absence is why this defect shipped: the
+SVG in a viewer and the PNG in an image viewer, both compared against the rendered panel.
+
+Do it for **two** panels with different shapes — one with a hand-built legend and size key
+(`AccessGapScatterPanel`), one without — because the legend behaviour is precisely what differs
+between the two export paths.
+
+Unit tests: the SVG clone carries inlined styles for tick labels and axis strokes; both entry points
+still resolve with their existing signatures; the PNG path resolves for a container holding more than
+one SVG.
+
+---
+
+## Part B — Implementation map
+
+`.claude/models.local.json` has no local override, so the default applies: `implementation.runtime`
+is `claude`/`sonnet` — the Orchestrator implemented directly, no Codex dispatch.
+
+**Dependency decision (risk section, and Part C's approval gate):** no library added. Checked
+first, per the WO's own instruction, and it held up: the platform's own `<foreignObject>` → `Image`
+→ `<canvas>` pipeline works for arbitrary DOM rasterisation with no dependency at all. The one
+obstacle — **confirmed live, not assumed** — is that Chrome taints the canvas on `toBlob`
+unconditionally the moment the source SVG contains a `<foreignObject>` with HTML content, even with
+zero external references (a minimal repro: a `<foreignObject>` holding one `<div>` with inline
+`color: red` styling and no images/fonts/external refs still throws `SecurityError: Tainted
+canvases may not be exported` when the SVG is loaded via `URL.createObjectURL`). The SAME SVG loaded
+via a `data:` URI instead does **not** taint the canvas — confirmed with an identical minimal repro,
+then re-confirmed end-to-end against the real `exportChartPng`/`ChartFrame` (real Chrome, via the
+dev harness). This is why the approval gate never triggered: the platform-only approach IS viable,
+it just needed the `blob:` → `data:` URI swap in `rasterize` (`exportChart.js`), documented inline
+there.
+
+**Canvas tainting on the PRE-FIX path:** checked per the risk section's own instruction ("may
+already be failing on it"). It was not — a plain SVG-only blob (no `foreignObject`) loaded via
+`URL.createObjectURL` does **not** taint the canvas; the exposure is specific to the `foreignObject`
+this WO's PNG path adds, not a pre-existing defect.
+
+**Verification (both real-browser, via the dev harness's module graph — `dev/entries.jsx` never
+committed a probe entry, all verification was done by dynamically rendering `ChartFrame` into a
+detached container and calling the real `exportChartSvg`/`exportChartPng`):**
+
+- Panel shape WITH a hand-built legend + size key (mirroring `AccessGapScatterPanel`: MUI's own
+  legend hidden, a `<div>` HTML legend with a coloured swatch, a second `<svg>` "size key" beside
+  the chart): PNG rasterised at 2x scale, no taint, and pixel-sampling the produced PNG at the
+  swatch's and size-key's known screen coordinates read back their EXACT source colours
+  (`rgb(25,118,210)` / `#1976d2` and `rgb(156,39,176)` / `#9c27b0`) — the legend and size key are
+  genuinely present in the raster, not just "no error thrown". SVG export of the same panel:
+  contains `MuiChartsSurface-root` (the chart), does NOT contain the legend's own text/markup —
+  chart-only as designed.
+- Panel shape WITHOUT a hand-built legend (plain `BarChart` inside `ChartFrame`): both exports
+  resolve cleanly, no regression for the common case.
+
+Context package used: `exportChart.js` (rewritten in full, was short), `ChartFrame.jsx:42-108`
+(the `runExport`/`exportOptions` wiring) and `:137-151` (`chartRef`, the export root — confirmed
+correct: it wraps `content` only, excluding the meta/export-button footer), `chartsTranslations.ts`
+(new `EXPORT_SVG_TOOLTIP`/`EXPORT_PNG_TOOLTIP` keys, all four locales).
+
+---
+
+## Part C — Orchestrator only
+
+> **STOP — everything below addresses the Orchestrator.**
+
+**Tier 3 · verification: opened files for two panel shapes, plus the unit tests above**
+
+Shared-core, and — depending on scope item 2's answer — a dependency addition, which is its own
+approval surface under Core Behaviour. If a library is needed, **stop and get the operator's
+approval for that specific dependency** before adding it; the approval given on 2026-08-25 was for
+the approach, not for a named package.
+
+- `reviewer` — the inlining's completeness and the taint/font questions.
+- `ui_reviewer` — whether the two buttons now read as two different things to a user.
+- `sec_reviewer` — not run; no auth, data or exposure surface.
+
+### Release
+
+**Minor → 3.3.0**, per the operator. The PNG's *content* changes (it now includes the legend and
+footnotes), so the CHANGELOG entry must **lead** with that, in the style `UCM-CHART-15` established:
+a consumer who bumps and finds their exported PNGs different should read why in the first line, not
+find it in a bullet.
+
+### Register
+
+Row `UCM-CHART-17`, both review notes, the published version, landing SHA(s) in a second commit
+before the push. Record what the opened files actually looked like — that evidence is the point.
+
+Consumer adoption (hram's pin bump) is a separate row; a shared-core fix that is published but not
+consumed is not finished.
+
+### Log
+
+- **2026-08-25** — Envelope authored after the operator reported exports producing graphically very
+  different plots. Diagnosed from source, not reproduced by the Expertenchat: the operator has seen
+  the files. Option C chosen — SVG stays vector and chart-only, PNG becomes what the screen shows.