@micha.bigler/ui-core-micha 2.40.0 → 2.41.1

package/work-orders/THEME-11.md

@@ -0,0 +1,208 @@
+# THEME-11 — The kit has no opinion on chart margins, so every chart in the estate inherits MUI's
+
+## Part A — Envelope
+
+**Goal.** Give the chart presets a margin default of their own, so charts stop falling back to
+MUI X's `DEFAULT_MARGINS` of 20 px on all four sides, and trim the one comparable block in
+`ChartFrame`. The whitespace around plots shrinks everywhere at once, without each consuming
+panel having to hand-tune a `margin` prop.
+
+**Why — measured, not estimated.** hram's four KPI cards were taken apart pixel by pixel. The
+chart is 270 px tall and its plot area is 202 px; the remaining 167 px is furniture, and the
+budget accounts for the card's observed ~370 px exactly:
+
+| Block | px | Owner |
+|---|---|---|
+| `ChartFrame` root padding (`p: 2`) top | 16 | this package |
+| Title text | ~24 | this package |
+| Title box `mb: 2` | 16 | this package |
+| `margin.top` | 20 | **MUI default** |
+| **Plot area** | **202** | — |
+| x-axis height (`DEFAULT_AXIS_SIZE_HEIGHT`) | 25 | MUI default |
+| `margin.bottom` | 20 | **MUI default** |
+| Forced blank (`minHeight 300` over `height 270`) | 30 | hram — its own `FIX-16` |
+
+The forced blank is **centred, not stacked at the bottom**: `ChartFrame`'s content box is
+`display: flex` with `alignItems: center`, so a `minHeight` above the chart's own height splits
+evenly — 15 px above the chart and 15 px below. It is listed once here for the total.
+| `ChartFrame` root padding bottom | 16 | this package |
+
+**The MUI defaults apply because this package never forms an opinion.** `spaceForRotatedTicks`
+returns the caller's `margin` untouched unless the x-ticks are rotated *and* the caller left
+`bottom` unset — so for the ordinary case it hands `margin: undefined` straight to
+`MuiBarChart`, and `DEFAULT_MARGINS = { top: 20, bottom: 20, left: 20, right: 20 }` takes over.
+THEME-9 gave the kit axis *sizing*; margins were never in its scope. Every chart in every
+consuming app has been paying those 20 px since.
+
+**What each side is actually for**, which is what makes the trim safe rather than a guess:
+- `margin.left` sits **outside** the y-axis width — this package's own comment records
+  `drawingArea.left = margin.left + axisSizeLeft`. The tick labels live in `axisSizeLeft`, so
+  `margin.left` is pure padding.
+- `margin.bottom` sits **below** the x-axis block; `DEFAULT_AXIS_SIZE_HEIGHT` already contains
+  the tick label.
+- `margin.top` is the only one carrying real content: the topmost y tick label is centred on its
+  gridline and overhangs the plot by roughly half a caption line-height (~9 px). This is why the
+  top cannot simply be trimmed to match the others.
+- `margin.right` is the risky one — see the scope note.
+
+**Scope.**
+
+1. **A margin default in the shared chart path**, applied when the caller passes no margin and
+   merged per-side (not wholesale) when the caller passes a partial one, so an explicit
+   `{ left: 60 }` does not silently reinstate 20 px on the other three sides:
+   - `top: 10` — leaves the ~9 px overhang of the topmost tick label its room. **Not 8**: at 8
+     that label sits on the edge.
+   - `bottom: 8`
+   - `left: 8`
+   - `right: 16` — **deliberately a smaller trim than the other sides.** On a band x-axis the
+     tick labels are centred and 8 would be fine, but on a **linear** x-axis the last tick label
+     sits *at* the edge and overhangs by half its width (~13 px for a four-character label at
+     caption size). 16 is the value that survives both. Do **not** make this conditional on
+     scale type: that is inferred behaviour serving no named consumer, and a chart that genuinely
+     needs more can pass `margin` explicitly.
+2. **`ChartFrame`'s title box `mb: 2` → `mb: 1`** (16 → 8 px).
+3. Apply consistently across the presets that share the path (`BarChart`, `LineChart`,
+   `TimeSeriesChart`), so consumers do not have to know which chart type trims what.
+
+**Non-goals / do-not-touch.**
+- **`CHART_FRAME_ROOT_SX = { p: 2 }` stays.** Trimming it would help the left and right edges
+  too, but `ChartFrame` wraps non-chart content as well, and its padding is what makes a panel
+  read as a card. That is a separate proposal with a different blast radius, not a rider here.
+- No change to axis sizing, tick formatting or label placement — THEME-9 owns those and they
+  are working.
+- No new props. This is a default, not a feature.
+
+**Tier 3** — shared-core. `reviewer` mandatory; `ui_reviewer` too, the deliverable being visual.
+
+**Two traps this WO must not walk into.**
+
+1. **`spaceForRotatedTicks` decides "did the caller set bottom?" by `margin?.bottom != null`.**
+   If a package-level default margin object is injected *before* that check, every rotated-tick
+   chart sees it as caller-set and loses its extra bottom space — hram's `RatioMetricsPanel`
+   runs x-labels at −45° and −90° and would clip them. The default must be applied so that
+   `spaceForRotatedTicks` still distinguishes a genuine caller margin from the package default,
+   or the rotated path must be computed first and the default merged under it.
+2. **`MUI_CHART_MARGIN_BOTTOM = 20` in `chartDefaults.js` is a hard-coded mirror of MUI's
+   default**, used as the base when the rotated path computes extra bottom space. It must move
+   with the new default, or rotated charts get their extra height added to the wrong base.
+
+**Tests to write.** Narrow, but these three are the ones that catch a real break:
+- A rotated-tick chart still receives its enlarged bottom margin (trap 1 — the regression this
+  change is most likely to cause).
+- A caller-supplied partial margin keeps its own value on the side it set and gets the new
+  default on the others (the merge semantics in scope 1).
+- A chart with a linear x-axis does not clip its last tick label at the new right margin.
+
+**Risks.**
+- **The blast radius is every chart in every consuming app**, and it lands the moment each app
+  bumps its pin — not at publish. A single wrong side value is therefore an estate-wide visual
+  regression rather than a local one. That is also the point of doing it here rather than in
+  each panel, but it raises the bar on the rendered check.
+- **Panels that already hand-tune `margin`** (hram's `RatioMetricsPanel` passes
+  `{ left: 60, right: 8, top: 20, bottom: … }`) must be unaffected on the sides they set. This
+  is what scope 1's per-side merge is for; whole-object replacement would break them.
+- The numbers above are derived from a caption-sized tick label. A consuming app with a
+  markedly larger chart font would need more top margin. Do not build for that — no consumer
+  has it — but state the assumption in the docs.
+
+**Delivery is not done at publish.** hram is the consumer that reported this, and its pins for
+THEME-8, THEME-9 and THEME-10 are all already open. Take this one in the same bump rather than
+adding a fourth pending hop.
+
+## Part B — Implementation map — ADDRESSED TO THE IMPLEMENTER
+
+Codex not dispatched: `.claude/codex-status.md` already carried a same-day `unavailable` line —
+implemented directly in Claude, authorship flip, `reviewer` + `ui_reviewer` mandatory (already
+required at Tier 3).
+
+### What landed
+
+- `chartDefaults.js`: `PACKAGE_DEFAULT_MARGIN = { top: 10, bottom: 8, left: 8, right: 16 }`
+  (exported) and `withMarginDefaults(margin)` (per-side merge, number-shorthand expansion).
+  `MUI_CHART_MARGIN_BOTTOM` moved `20 → 8` to match the new baseline (trap 2).
+- `BarChart.jsx`/`LineChart.jsx`: `spaceForRotatedTicks` still runs FIRST, on the caller's
+  UNMODIFIED `margin` — its own `callerSetBottom` check (`margin?.bottom != null`) therefore
+  still tells a genuine caller margin from "nothing set" correctly (trap 1 avoided by ordering,
+  not by threading a flag through the shared helper). `withMarginDefaults` is applied AFTER,
+  wrapping `rotatedTickSpace.margin` on the way into `MuiBarChart`/`MuiLineChart` — so a
+  rotation-computed `bottom` (already present on that object) is preserved by the merge, and
+  only genuinely-unset sides get the package default.
+- `TimeSeriesChart.jsx`: no change needed — it never sets its own `margin`, so it inherits
+  `BarChart`'s new default automatically through composition.
+- `ChartFrame.jsx`: title row `mb: 2 → mb: 1`. Controls row `mb: 2` left untouched (not named).
+  **Deliberately unconditional** (`ui_reviewer` U3 asked whether this should be scoped to only
+  chart-preset consumers, matching the margin trim's scope): `ChartFrame` wraps non-chart
+  content too, and scope item 2 names the title box specifically, with no "only when a chart
+  preset is the child" qualifier anywhere in Part A — a scatter-backed or bespoke-SVG panel
+  gets the tighter title spacing but keeps whatever margin its own content uses, which is
+  correct: the title row and the plot margin are two independent pieces of furniture, not one
+  setting that should move together.
+
+### Scope gap surfaced, not silently folded in
+
+`ScatterChart` (THEME-10, same day, not yet published) passes its `margin` prop straight
+through with no default handling at all — it would keep MUI's flat 20px default while
+`BarChart`/`LineChart`/`TimeSeriesChart` get 8/10/16. THEME-11's own scope item 3 names exactly
+three presets, not four, and `ScatterChart` didn't exist when this WO's Part A was authored.
+Flagging this explicitly rather than extending scope silently: `ScatterChart` should likely get
+`withMarginDefaults` too, in a follow-up (or when `ScatterChart`'s own version bumps). **This is
+NOT the same seam as the right-margin note below** — `ScatterChart`'s X axis is always linear by
+construction (THEME-10 scope), so if/when it does adopt `withMarginDefaults`, its own rendered
+check needs to re-examine the right-margin question specifically, not inherit this WO's
+"no consumer has it" conclusion by assumption.
+
+### Verification detail beyond the WO's own risk note — corrected after review
+
+The rendered check found that a wide, locale-grouped tick value (`"1,000"`, 6 characters)
+leaves only ~1px of clearance at the new `right: 16` before MUI's own internal `shortenLabels`
+truncates it to `"1,0…"` — never actual overflow-clipping past the SVG boundary in either the
+narrow or wide case. Two corrections to the original note, from `reviewer`/`ui_reviewer`:
+
+- **The grouped formatting is MUI's OWN default tick rendering, not THEME-9's
+  `defaultNumericTickFormatter`** (`reviewer`/`ui_reviewer` finding, independently confirmed:
+  neither `BarChart.jsx` nor `LineChart.jsx` wires a `valueFormatter` onto the x-axis — only the
+  y-axis gets THEME-9's default — and the dev fixture that produced `"1,000"` set none either).
+  This means the tight case is not a THEME-9-introduced interaction; it is how MUI itself has
+  always formatted a linear axis's ticks, now simply more VISIBLE because `right` shrank from
+  20 to 16.
+- **No real consumer hits this today** (`reviewer`, verified by grepping every hram panel that
+  actually consumes `BarChart`/`LineChart`/`TimeSeriesChart`: `CostMetricsPanel`,
+  `RatioMetricsPanel`, `AccessibilityPanel`, `TotalMetricsPanel`, `ReferralMetricsPanel`,
+  `GroupMetricsPanel`, `GenericAnalysisPlot` — every one uses `scaleType: 'band'`, none
+  `'linear'`. `AllocationPerformancePanel`, the panel this note originally worried about,
+  imports only `ChartFrame` from this package and draws its own bespoke SVG axes — it does not
+  go through `BarChart`/`LineChart` at all, so it is unaffected by this WO regardless.) The WO's
+  own explicit "do not build for a case no consumer has; state the assumption" therefore applies
+  cleanly, not just plausibly. The residual risk (`ui_reviewer`) is real but one hop removed: the
+  first FUTURE consumer that renders a linear x-axis through `BarChart`/`LineChart` with wide
+  values should re-check this margin before shipping, and there is no code-level guard that would
+  catch it automatically — recorded here so that check doesn't get skipped.
+
+### 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 — implemented directly in Claude.
+- **Review routing.** `reviewer` + `ui_reviewer`, concurrent, one background batch.
+- **Verification.** Package suite: `chartDefaults.test.js` gained a dedicated
+  `withMarginDefaults` describe block (pure-function contract) plus integration tests against
+  `BarChart`/`LineChart` (package default applied, rotated-tick chart still gets its enlarged
+  bottom margin — not the flat package default, partial-margin per-side merge, full-margin
+  passthrough, right > left/bottom by construction); full affected set (`BarChart.test.jsx`,
+  `LineChart.test.jsx`, `TimeSeriesChart.test.jsx`, `timeSeriesLegend.test.js`,
+  `ScatterChart.test.jsx`, `chartsPalette.test.js`) — 91 tests, green.
+  **Rendered check, done live** in the package's own dev harness: (1) the existing "Caller
+  overrides" `LineChart` fixture (−25° rotated ticks, no explicit margin — exactly trap 1's
+  shape) measured with NO overlap between the rotated tick labels and the axis title (15px
+  clear gap) — trap 1 confirmed avoided; (2) a new `LineChart (linear x-axis)` fixture added
+  and measured at two magnitudes — narrow (`"100"`) with 5px clearance from the SVG edge, wide
+  locale-grouped (`"1,000"`) with MUI's own truncation kicking in at ~1px clearance but never
+  actual clipping past the boundary (see the "beyond the WO's risk note" section above).
+- **Register & commit.** Advance the THEME-11 row with the reviewer verdicts. Coordinate the
+  consumer pin bump with THEME-8, THEME-9 and THEME-10 — all still open at publish time,
+  pending this WO's own reviews and a bundled version bump.