@micha.bigler/ui-core-micha 2.41.3 → 2.42.1

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

@@ -0,0 +1,265 @@
+# UCM-CHART-9 — `ChartFrame` is a card, not a chart: it must never take a fixed height
+
+- **Repo:** `ui-core-micha`, branch `main` (shared-core; publishes from `main`, no staging step)
+- **Tier:** 3 — shared-core, and this is a **live layout regression in a published version**.
+- **Status:** planned
+- **Workstream:** `CHART-*`
+- **Files:** `src/components/charts/ChartFrame.jsx` and its tests. `chartDefaults.js` only if the
+  resolver needs a second shape — see below; the preset behaviour is correct and must not change.
+
+> **Why — regression, observed on staging after hram bumped to 2.42.0.** `UCM-CHART-8` wired
+> `resolveChartHeight()` through the four chart presets **and through `ChartFrame`**. For the
+> presets that is right. For `ChartFrame` it is not, and the difference is what the box contains.
+>
+> In the `minHeight` alone / no `height` / no `aspect` branch, `resolveChartHeight` returns
+> `chartHeight = minHeight`, and `ChartFrame` now applies it:
+>
+> ```diff
+> -          minHeight,
+> +          minHeight: wrapperMinHeight,
+> +          height: chartHeight,
+> ```
+>
+> **A chart preset's box contains exactly one chart. `ChartFrame`'s box contains a whole card** —
+> title, toolbar, the chart, a legend, footnotes, export links. Turning its `minHeight` floor into a
+> fixed `height` makes the box shorter than its content, the content overflows, and **adjacent cards
+> visibly overlap**: the operator's screenshot shows a card title rendered over the chart of the card
+> above it and three sets of "Export SVG / Export PNG" stacked at different offsets.
+>
+> `UCM-CHART-8`'s own Files note recorded that `ChartFrame` "never destructures `height`" — and the
+> implementation then gave it one. The rule was written for presets and applied to a frame.
+
+---
+
+## Part A — Envelope (authoritative WHAT/WHY)
+
+### Goal
+
+`ChartFrame` stops setting a fixed `height` on its content box. Its `minHeight` goes back to meaning
+what its name says — a floor that content can exceed. The four chart presets keep `UCM-CHART-8`'s
+three-way resolution unchanged.
+
+### Definition of Done
+
+- [ ] **`ChartFrame` never applies `chartHeight` to its content box.** Its box takes `minHeight` as a
+      floor, as it did before 2.42.0. Whether that is done by not calling `resolveChartHeight` at
+      all, or by giving the resolver an explicit frame shape, is the implementer's call — but
+      `ChartFrame` must not end up with a fixed `height` in any branch.
+- [ ] **A `ChartFrame` whose content exceeds `minHeight` grows.** This is the regression, stated as
+      the acceptance criterion: content taller than the floor must extend the box, never overflow it.
+- [ ] **The four presets are untouched.** `ScatterChart`, `BarChart`, `LineChart`, `TimeSeriesChart`
+      keep `UCM-CHART-8` exactly as it landed — including the `aspect` branch that four live call
+      sites depend on. This WO narrows one consumer of the resolver; it does not revisit the rule.
+- [ ] **`ChartFrame`'s JSDoc is corrected.** 2.42.0 added a paragraph claiming `minHeight`
+      "sizes the content box itself" when there is no `height`/`aspect`. That sentence is the bug in
+      prose form and must go.
+- [ ] **`warnOnHeightMismatch` stays** on `ChartFrame` — a caller passing both is still worth a
+      dev-mode note, even though the frame no longer acts on `height`.
+
+### Non-goals
+
+- Do **not** revert `UCM-CHART-8`. Its preset behaviour is correct and is the fix hram needs; only
+  the frame's participation was wrong.
+- Do not change `resolveChartHeight`'s three-way rule for presets.
+- No consumer-side change in this WO.
+
+### Risks
+
+- **`ChartFrame` is used by every Research card in hram and by other consumers.** The change restores
+  pre-2.42.0 behaviour for it, so the risk is low in direction — but it is still a shared-core
+  publish, and the rendered check below is what proves it.
+- 2.42.0 is `latest` on the registry and carries this regression. Publish 2.42.1 promptly; note in
+  the register that 2.42.0 should not be adopted by a new consumer.
+- **hram's Detailed Results tab is fixed as of 2.42.0** (operator-confirmed, 2026-08-21) — it
+  crashed with React #185 before the bump (`HRAM-RES-29` item 1) and does not any more. What is
+  **not** established is *why*: the plausible mechanism is that deterministic sizing removed a
+  resize-driven `setState` loop, but nobody has traced it.
+  **Consequence for this WO, and the only reason it is mentioned here:** since we do not know what
+  fixed it, we cannot know whether moving `ChartFrame` back toward a floor disturbs it. Re-check the
+  tab after this lands. If the crash returns, that is a finding for `HRAM-RES-29` and a sizing
+  dependency worth understanding — not a reason to undo this fix.
+
+### Tests to WRITE — narrow
+
+- **The regression test:** a `ChartFrame` with `minHeight` and no `height`/`aspect`, containing
+  content taller than `minHeight`, does **not** receive a fixed `height` on its content box.
+- `ChartFrame` with `height` explicitly passed: `height` is still not applied as a fixed box height
+  (the frame is not a chart), and no exception is thrown.
+- The four presets' existing `UCM-CHART-8` tests stay green **unchanged** — if one of them has to be
+  edited, the change has leaked out of `ChartFrame` and that is a stop-and-report.
+
+**Rendered check before the hram pin bump — mandatory, and the reason this WO exists.** The unit
+tests for 2.42.0 were 188 green and said nothing about layout, because they cannot. Before hram's pin
+moves again, the affected cards are checked rendered at 375 px and 1280 px: Sensitivity, Access,
+Access Ladder, Allocation, Optimization. Named in the register note, with the substitution declared
+if capture is unavailable.
+
+---
+
+## Part B — Implementation map — ADDRESSED TO THE IMPLEMENTER
+
+### Context package
+
+**Named files to change:**
+- `src/components/charts/ChartFrame.jsx` — the fix (below).
+- `tests/ChartFrame.test.jsx:215-256` — the `describe('minHeight/height resolution (CHART-8)', …)`
+  block. It currently **asserts the bug as correct behaviour** (e.g. `minHeight` alone →
+  `style.height` toBe `'300px'`). Rewrite it to assert the fixed behaviour; rename the block to
+  `(CHART-9)`.
+
+**Do NOT touch (verified against the landed code):**
+- `src/components/charts/chartDefaults.js` — `resolveChartHeight` (lines ~289-298) and
+  `warnOnHeightMismatch` (lines ~306-315) keep their exact current contract. If the fix seems to need
+  a change here, that means the change has leaked out of `ChartFrame` — stop and report, don't edit.
+- `src/components/charts/{BarChart,LineChart,ScatterChart,TimeSeriesChart}.jsx` — all four still call
+  `resolveChartHeight({ minHeight, height, aspect })` for their OWN box, unchanged.
+- `tests/chartDefaults.test.js:441+` (`describe('resolveChartHeight (CHART-8)', …)`) and the four
+  presets' own test files — must stay green **unchanged**. If one needs an edit, stop and report.
+
+**The bug, exactly:** `ChartFrame.jsx:61-62` calls `resolveChartHeight({ minHeight, height, aspect })`
+and applies the result to its content box at `:109-125`:
+```jsx
+sx={{
+  width: '100%',
+  minHeight: wrapperMinHeight,
+  height: chartHeight,
+  aspectRatio: aspect,
+  ...
+}}
+```
+In the "no `height`, no `aspect`" branch, `resolveChartHeight` returns `chartHeight = minHeight` —
+correct for a preset's box (which holds exactly one chart) but wrong for `ChartFrame`'s box (which
+holds a whole card: title, toolbar, chart, legend, footnotes, export links). A fixed `height` there
+makes the box shorter than its content, and the content overflows into the next card.
+
+**What "restore pre-2.42.0 behaviour" means concretely** — before `UCM-CHART-8` (commit `11d362c`),
+`ChartFrame` had no `height` prop at all and its content box was:
+```jsx
+sx={{
+  width: '100%',
+  minHeight,
+  aspectRatio: aspect,
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+}}
+```
+i.e. `minHeight` applied raw, straight from props, never touched by any resolver; no `height` was
+ever set on the box.
+
+**The fix:** `ChartFrame`'s content box must end up equivalent to that — `minHeight` (raw, from
+props) as the box's only height-related sx property besides `aspectRatio`, and nothing ever sets
+`height` on the box. The `height` prop stays in `ChartFrame`'s signature (do not remove it — it is
+still a documented prop and `warnOnHeightMismatch('ChartFrame', { minHeight, height })` at line 61
+must keep firing on a caller passing both `minHeight` and a disagreeing `height`), it is simply no
+longer used to size the box. Whether you implement this by dropping the `resolveChartHeight` call
+from `ChartFrame` entirely (simplest — matches the pre-2.42.0 shape exactly) or by giving the
+resolver a second, frame-specific shape in `chartDefaults.js` that never returns a `chartHeight` is
+your call — but per the non-goals below, the existing `resolveChartHeight` export and its three-way
+preset contract must not change.
+
+**JSDoc fix:** `ChartFrame.jsx:19-26`'s docblock currently states: *"otherwise (no `height`, no
+`aspect`) it sizes the content box itself. Once `height` is set, `height` sizes the box…"* — that
+sentence describes the bug as intended behaviour and must be corrected to state that `minHeight` is
+always a floor on `ChartFrame`'s box and `height` is never applied to it (only used for the
+dev-mode mismatch warning).
+
+**Regression check while you're in there:** hram's Detailed Results tab crashed with React #185
+before the 2.42.0 bump and stopped crashing after it (`HRAM-RES-29` item 1, unconfirmed hypothesis:
+deterministic sizing removed a resize-driven `setState` loop). This fix moves `ChartFrame` back
+toward non-deterministic sizing for that one prop. You are not expected to reproduce or verify the
+hram-side crash — the Orchestrator does that separately after your diff lands — but do not add any
+new resize-driven effect to `ChartFrame` while touching this code.
+
+Work from this package; do not explore broadly from scratch — open only the named files to verify.
+If you must dig deeper, delegate to a read-only Explore sub-agent (Haiku).
+
+### Target repo working directory (absolute)
+
+`C:\Users\Micha Bigler\Documents\webapps\ui-core-micha`
+
+### Preamble — binding, read before doing anything else
+
+The text in this file is the COMPLETE spec — the committed WO content, not a plan to refine; there
+is no separate plan file. Read the nearest `AGENTS.md`, the relevant `.codex/skills/<role>/SKILL.md`,
+and this repo's own `MEMORY.md` ONLY for conventions. Stay in scope; do not touch
+auth/permissions/deps/schema/CI unless this spec says so; do not update `MEMORY.md`. **Do NOT edit
+`WORK_ORDERS.md`** — the register row and the review verdicts are the orchestrator's alone. Do NOT
+`git add`/`commit`/`push` — leave every change uncommitted in the working tree for the orchestrator's
+independent review. WRITE the tests the "Required tests to WRITE" section (Part A) calls for AND
+**RUN the tests you just wrote** to confirm they execute and pass — that is the ONLY test run you do
+(NOT the app's affected/full suite, NOT any review). The orchestrator re-runs the authoritative set
+and does the independent review after you finish — those are the gate; your own run does not count
+as the gate.
+
+Narrate continuously: a `PLAN: <step1> | <step2> | …` line up front, then a single-line
+`PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (and `… done` on
+completion), spaced so no gap exceeds ~2 min, stdout unbuffered, plus exactly one final
+`RESULT: DONE|BLOCKED <reason>`.
+
+---
+
+## 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.** Everything below describes what the Orchestrator does AFTER you finish. You do none of it
+> — no reviewers, no verification run, no register edit, no commit. You ARE the invocation described
+> below; do NOT shell out to `codex exec`.
+
+### Execution directive
+
+Implement through `codex exec` in the background — invoked directly via Bash (never the
+`debugger`/`*_coder` Agent wrappers) with BOTH flags `--skip-git-repo-check` and
+`--dangerously-bypass-approvals-and-sandbox`, `cwd` = the working directory above (never
+`…\webapps`). Fallback to direct Claude implementation only on Codex quota/rate-limit/non-zero exit —
+check `.claude/codex-status.md` first per its own rule (no line for 2026-08-22 → use Codex). The
+fallback flips authorship, making an independent `reviewer` mandatory even if it already was.
+
+### Review routing (Tier 3, shared-core)
+
+- `reviewer`: **yes**, full context, Sonnet-pinned, background.
+- `ui_reviewer`: **yes** (diff touches frontend), full context, background, same batch as `reviewer`.
+- `sec_reviewer`: not required — no auth/security surface in this diff.
+- Both run concurrently; neither is skippable; commit waits for both clean.
+
+### Verification (the authoritative run — Codex's own run is not the gate)
+
+1. **Test gate:** `npx vitest run tests/ChartFrame.test.jsx tests/chartDefaults.test.js
+   tests/BarChart.test.jsx tests/LineChart.test.jsx tests/ScatterChart.test.jsx
+   tests/TimeSeriesChart.test.jsx` (adjust filenames to whatever actually exists — the affected-area
+   set per AGENTS.md "Test scope": `ChartFrame` itself plus every consumer of `resolveChartHeight`).
+   All must pass; the four presets' pre-existing assertions must be **byte-identical**, not just
+   green — a changed preset assertion means the fix leaked scope.
+2. **Rendered check — this WO's own commit gate, scoped to what this repo can render.** This repo
+   has no prototype artifact, so the generic prototype side-by-side gate does not apply; this WO's
+   own Envelope names a rendered check instead, and it is honoured here at the scope this repo can
+   actually reach:
+   - Run `npm run dev` (Vite) and open the dev harness at 375 px and 1280 px. It already contains
+     `ChartFrame` "shape check" stories that mirror three of the five named hram cards — "Allocation
+     performance", "Access gap", "Optimization results" (`dev/entries.jsx`, search `shape check`).
+     Confirm none of them, nor any neighbouring card, show overlapping title/content/export rows at
+     either width.
+   - Additionally render (ad hoc, in the same dev session — e.g. a temporary story or by editing an
+     existing one's children) a `ChartFrame` with a `minHeight` smaller than its actual content, to
+     directly exercise the Definition of Done's acceptance criterion: the box must grow to fit the
+     content, not overflow it. Revert any temporary dev-harness edit before commit (or keep it only
+     if it's a genuine permanent addition worth keeping — your call, but say which in the Notiz).
+   - This repo's harness has no "Sensitivity" or "Access Ladder" story, so the **full five-card
+     rendered check the Envelope describes ("before hram's pin moves again") is NOT done by this WO**
+     — it cannot be, without linking a built `ui-core-micha` into a running hram dev server. Declare
+     this explicitly in the register Notiz as a carried-forward precondition on whichever WO next
+     bumps hram's pin past 2.42.0, not a silently dropped gate.
+   - Declare screenshots-vs-DOM-inspection substitution explicitly if real screenshots aren't taken.
+
+### Register + commit
+
+- `WORK_ORDERS.md` row → `done`, with: the named review verdicts (`reviewer` + `ui_reviewer`, no
+  open findings — or the findings and their resolution), the test gate result, the rendered-check
+  scope actually achieved (dev harness only, full hram five-card check carried forward), and which
+  evidence from `.claude/codex-status.md` was used (or that no fallback was needed).
+- Note in the Notiz: **publish 2.42.1 promptly after commit** (per Part A Risks — 2.42.0 is `latest`
+  on the registry and carries this regression) and confirm the version bump lands in the same commit
+  or a clearly-linked follow-up; the register row must name whichever it was.
+- Commit message: single concise English subject line (e.g. `fix(ChartFrame): stop applying a fixed
+  height to the card box (CHART-9)`). Push to `main` (this repo publishes from `main`, no `develop`
+  step) once review + tests are clean.