@micha.bigler/ui-core-micha 3.14.3 → 4.0.0

package/work-orders/THEME-9.md

@@ -1,194 +0,0 @@
-# THEME-9 — Charts spend more space on furniture than on data
-
-## Part A — Envelope
-
-**Goal.** Give the chart presets back the space their axis furniture currently reserves and
-does not use, stop broadcasting one axis label onto every axis, keep the axis label out of
-the tick band, and make short, locale-correct tick numbers the default.
-
-**Why — measured in a consuming app (hram), not estimated.** One KPI card, "Coverage":
-
-| layer | size | owner |
-|---|---|---|
-| card (`Paper`, 16 px padding) | 470 × 372 | app |
-| chart wrapper `Box` | 436 × **300** (`minHeight: 300`) | **this package** — the SVG inside is 270 tall, so **30 px are dead** |
-| SVG | 436 × 270 | this package |
-| **plot area** | **301 × 175** | — |
-
-**The plot is 45 % of the SVG and 30 % of the card.** 135 px of width and 95 px of height are
-consumed inside the SVG. Walking the left edge outward: 17 px card padding, then **60 px of
-blank between the SVG edge and the axis label**, then 9 px, then the first tick — 104 px before
-a number appears. Below the chart: 30 px of blank inside the SVG under the axis label, then
-another 32 px to the card edge.
-
-Three further findings from the same app, all measured:
-
-1. **One label is applied to every axis.** `withAxisDefaults` ends with
-   `label: axis.label || label`, so a single `yAxisLabel` lands on *all* axes in the array. In
-   hram's dual-axis chart both y-axes therefore carry the identical 43-character string
-   `"Treated / Untreated / Saved / Avoid. Deaths"`, each reserving 65 px of a 206 px-wide chart.
-2. **The axis label is drawn inside the tick band.** On hram's Accessibility chart **4 of 4**
-   y-tick labels overlap the axis label — the rotated title runs straight through
-   `"0.0 min"`, `"50.0 min"`, … The same happens on an x-axis whose tick labels are rotated
-   (30+ ward names over the label `"Ward"`). The space reserved for rotated ticks does not
-   actually keep the label clear of them.
-3. **Ticks carry units and needless decimals.** `"0.0 min"`, `"50.0 min"` — the unit appears in
-   every tick *and* twice in the label (`"Accessibility (minutes) (min)"`). Elsewhere MUI
-   truncates ticks it cannot fit, rendering `"0.0…"`, `"50.0…"`. `BarChart` sets no default tick
-   formatter at all, while `TimeSeriesChart` already applies one conditionally — so every app
-   re-solves this, and where nobody remembered, the numbers are wide and truncated.
-
-**Scope.**
-
-1. **Shrink the default margins and the axis-size reservation.** MUI X sizes axes itself; the
-   generous fixed values here predate that. Target the measured waste: ~60 px of blank left of
-   the label and ~30 px below it. Re-measure in a consuming app afterwards — the number to beat
-   is "plot area = 45 % of the SVG".
-2. **Stop broadcasting the label.** An axis label is set on the axis that needs it, not on every
-   axis in the array. Add a test that pins this: one label must never land on two axes. That is
-   the exact defect measured above, and nothing currently prevents it.
-3. **Keep the label out of the tick band.** Whatever space rotated or long tick labels occupy
-   must be excluded from where the axis label is placed. Verify with the real case — rotated
-   45° ward names, and a y-axis whose ticks are wide.
-4. **A default tick formatter for `BarChart`** (and any preset lacking one): short numbers, no
-   decorative decimals, no unit in the tick. **Do not simply switch on `Intl` compact
-   notation** — measured across the four locales this package's consumers use:
-
-   | value | de-CH | en | fr | sw |
-   |---|---|---|---|---|
-   | 12 500 | **`12'500`** | `12.5K` | `12,5 k` | **`elfu 12.5`** |
-   | 998 000 | **`998'000`** | `998K` | `998 k` | **`elfu 998`** |
-   | 1 000 000 000 | `1 Mrd.` | `1B` | `1 Md` | `1B` |
-
-   German does not compact thousands **at all** — exactly the range these charts live in — and
-   Swahili puts a word in front of the number, which is wider than the raw value. So compact
-   notation alone does not solve the width problem and in one locale makes it worse. A
-   per-axis unit chosen once (with the unit named in the axis label) does. Also note: a
-   hand-rolled `"B"` suffix would be **wrong in German**, where *Billion* is 10¹² — `Intl` gets
-   this right (`Mrd.`), hand-rolled suffixes do not.
-5. **Document the decision rule in `DESIGN.md`**, where a developer will find it at the call
-   site:
-   - **Categorical axis → no title by default.** The tick values are names; a title only
-     restates their type. Exception: ticks that are codes or abbreviations whose kind is not
-     self-evident.
-   - **Numeric axis → title carries the quantity and the unit.** A bare number is meaningless
-     without one. Exception: the ticks already show the unit (`%`, a currency symbol).
-   - **The unit belongs in the title once — never in every tick.**
-
-**Non-goals / do-not-touch.** No new chart types, no colour or typography changes, no change to
-what any chart plots. **Do not auto-suppress axis labels** — make them opt-in, but leave the
-decision with the caller; silently dropping a label someone deliberately set is a worse failure
-than the redundancy we are removing. Do not fix any of this per-app with `sx` overrides.
-
-**Tier 3** — shared-core surface. `reviewer` mandatory, `ui_reviewer` too: the visible result is
-a layout change in every consuming app.
-
-**Tests to write.** The one-label-per-axis assertion (scope 2) — it is cheap and it is the
-defect that actually shipped. A formatter test with the four locales above as fixtures, so the
-German and Swahili behaviour is pinned rather than rediscovered. Margins and overlap are carried
-by the rendered check, not by unit tests.
-
-**Risks.**
-- **Estate-wide visual change**, in apps nobody is currently working on. Name it in the release
-  notes; do not let it arrive as a surprise.
-- **Tighter margins can clip** where they previously over-reserved. The overlap fix (scope 3)
-  and the margin cut (scope 1) pull in opposite directions — do them together and measure, or
-  the second will re-create the first.
-- The tick formatter changes numbers on screens used for teaching. Rounding that hides a
-  meaningful difference is worse than a wide label: keep full precision in tooltips and tables,
-  compact only where space is scarce.
-
-**Delivery is not done at publish.** Consuming apps need their pin bumped and their charts
-looked at — hram first, where all of this was measured, and where the app-side follow-up is
-tracked as `FIX-13`.
-
-## Part B — Implementation map — ADDRESSED TO THE IMPLEMENTER
-
-Codex was not dispatched: `.claude/codex-status.md` already carried a same-day (2026-08-14)
-`unavailable` line (recorded earlier during `THEME-8`), so per the known-unavailable shortcut
-the Orchestrator implemented directly, which flips authorship — `reviewer` + `ui_reviewer`
-became mandatory (already required at Tier 3).
-
-### What landed, and why (measured, not guessed)
-
-- **`withAxisDefaults` label broadcast (scope 2).** Fixed: the single `label` argument now falls
-  back only onto `index === 0` of a multi-entry axis array — mirrors MUI's own
-  `position: 'left'`-only-on-first-entry default. Test: `chartDefaults.test.js`.
-- **`sizeYAxisForContent`, new (scope 1/3).** MUI's own y-axis width default is a flat 45px+20px
-  regardless of tick content (verified against `@mui/x-charts`' `DEFAULT_AXIS_SIZE_WIDTH` /
-  `AXIS_LABEL_DEFAULT_HEIGHT` and its `useChartDimensions` selector: margin and axis-size are
-  ADDITIVE, not nested — confirmed pixel-for-pixel against a live hram render, see below). This
-  sizes a linear y-axis from its own `min`/`max` or the plotted series, mirroring
-  `spaceForRotatedTicks`'s existing glyph-width heuristic.
-- **`defaultNumericTickFormatter`, new (scope 4).** Locale-grouped, non-compact by default —
-  verified live against `Intl.NumberFormat` output for all four locales (de-CH does not compact
-  thousands at all; sw's compact form is WIDER than the raw number).
-- **DESIGN.md #8a, new (scope 5).** The categorical/numeric axis-title rule.
-- **Not originally scoped, added because scope 5 required it:** `BarChart`/`LineChart` used to
-  hard-`throw` unless BOTH `xAxisLabel` and `yAxisLabel` were supplied — this made #8a's stated
-  "categorical axis gets no title by default" unachievable through either preset (`ui_reviewer`
-  finding U1). Both labels are now optional; omitting one renders no title for that axis. This is
-  the change FIX-13 needs to actually remove a title.
-
-### The Coverage-KPI-card measurement itself was NOT a package-level bug
-
-Live DOM measurement in the running hram app (`localhost:8000`, Basic Results → Coverage card)
-traced the Envelope's own "60px blank / 30px dead" numbers to their exact source:
-`drawingArea.left = margin.left + axisSizeLeft` (MUI's own `useChartDimensions` selector) — the
-60px is hram's OWN `margin={{left: 60, ...}}` prop on `TotalMetricsPanel.jsx`, stacking
-ADDITIVELY with MUI's separate ~65px axis-width reservation, not one containing the other. That
-duplication is `FIX-13`'s item 6 to fix (trim the app's own margin now that this package sizes
-the axis itself), not something `THEME-9` could fix by itself — packages can right-size their own
-axis reservation, not an app's separately-chosen margin.
-
-### Review findings, fixed before commit
-
-- **`reviewer` R1 (P1):** `sizeYAxisForContent`'s series-to-axis matching used
-  `(item.yAxisId ?? undefined) === (axis.id ?? undefined)`, which only matches when BOTH sides are
-  literally `undefined` — but MUI assigns an unmarked series to the FIRST axis in the array
-  (`yAxisIds[0]`), not to "no axis". This made the sizer a silent no-op for the PRIMARY axis of
-  exactly the dual-axis case (`TimeSeriesChart`'s `CHART-5` feature) that motivated this WO. Fixed:
-  match against `yAxis[0]?.id` as the default, not `undefined`. Regression test added.
-- **`ui_reviewer` U1 (P1):** see "not originally scoped" above — labels made optional.
-- **`ui_reviewer` U3 (P2):** the sizer used the theme-wide tick font size even when a caller
-  overrode `tickLabelStyle.fontSize` per-axis. Fixed: reads the axis' own (already-merged)
-  `tickLabelStyle.fontSize` first, falling back to the theme default only if absent.
-- **`ui_reviewer` U5 (P3):** the label-thickness term was derived from `theme.typography.body1`,
-  which only coincidentally matches MUI's own HARDCODED 14px axis-label font
-  (`ChartsYAxisImpl.js` sets `fontSize: 14` after spreading `body1`, so it always wins regardless
-  of theme). Fixed: a named `MUI_AXIS_LABEL_FONT_SIZE_PX = 14` constant, decoupled from theme.
-- **`ui_reviewer` U2 (P2, accepted as a documented limitation, not fixed):** the width estimate is
-  driven by the axis' own `min`/`max`/series values, not MUI's actual "nice-tick" rounding, which
-  can occasionally round a domain's extremes outward to a longer string. The existing 1.1x safety
-  factor absorbs small overshoots; a tighter fix would require duplicating MUI's own tick
-  algorithm, out of proportion for this WO. The rendered check below is the actual proof either way.
-- **`ui_reviewer` U4:** claimed `TimeSeriesChart.jsx` bypasses `withAxisDefaults`/
-  `sizeYAxisForContent` entirely. Verified against source: `TimeSeriesChart` renders through this
-  package's own `<BarChart>` (not `MuiLineChart` directly), so its `yAxis` array — including the
-  dual-axis case — DOES flow through both functions. Not acted on; recorded here so the claim
-  isn't silently dropped.
-
-### Target repo
-
-`C:\Users\biglmi\Documents\webapps\ui-core-micha`
-
-## Part C — Orchestrator only — NOT ADDRESSED TO THE IMPLEMENTER
-
-> **If you are the implementer reading this work order as your own specification: STOP at this
-> line.**
-
-- **Execution.** Codex known-unavailable today (see Part B) — implemented directly in Claude.
-- **Review routing.** `reviewer` + `ui_reviewer`, concurrent, one background batch — both ran,
-  findings above, all in-scope findings fixed before commit.
-- **Verification.** The package's own affected-set suite (`BarChart.test.jsx`, `LineChart.test.jsx`,
-  `TimeSeriesChart.test.jsx`, `timeSeriesLegend.test.js`, `chartDefaults.test.js` — 60 tests,
-  green). **The rendered check in hram could NOT be completed live in this session** — the Browser
-  pane only carries real viewport dimensions for the tab the operator has actually displayed;
-  freshly-opened tabs (both a new hram tab and ui-core-micha's own dev harness) measured 0×0 and
-  produced negative-width SVG rect errors as a direct consequence, not a code defect. The BEFORE
-  numbers (Coverage KPI card) WERE captured live from the properly-displayed hram tab and are
-  quoted above; the AFTER re-measurement is deferred to `FIX-13`, which needs it anyway once
-  hram's pin is bumped (its own WO already orders re-measurement after the pin bump, so this
-  doesn't lose anything — it was always going to happen there).
-- **Register & commit.** Advance the THEME-9 row with the reviewer verdicts. Track the consumer
-  pin bumps (hram = `FIX-13`) — this WO is not done at publish.