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

package/work-orders/CHART-2.md

@@ -1,222 +0,0 @@
-# WORK ORDER CHART-2 (ui-core-micha) — a time-series chart preset with range picker and series toggles
-
-**EXECUTION DIRECTIVE.** If you are the implementer reading this as your own spec, this section is not
-addressed to you — it tells the Orchestrator how to invoke you; you ARE that invocation, do not shell
-out to `codex exec`. Orchestrator: 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`, prompt passed as a positional argument from this
-file. Fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit.
-
-Feature-level WO (Expertenchat envelope). Extends CHART-1. Operator request 2026-08-04 from jg's event
-activity chart; the same controls are wanted wherever a time series is charted, and `django-core-micha`
-ACT-1 makes activity data available to every app.
-
-## TIER
-Tier 2 — shared-core UI consumed by every app. Independent `reviewer` + `ui_reviewer` mandatory.
-
-## WHY
-
-CHART-1 already ships `ChartFrame` (Paper + title + **toolbar slot** + loading / error / empty +
-responsive container + SVG/PNG export + a11y), a themed `BarChart`, `getNeutralChartPalette` and
-`chartsTranslations`. The frame's toolbar slot exists for exactly this and is currently unused by any
-consumer.
-
-jg's `ActivitySection.jsx` bypasses the kit entirely (`import { BarChart } from '@mui/x-charts/BarChart'`
-at `:9`) and hand-rolls its own `Paper`, loading, error and empty states. Rather than jg building a
-range picker and series checkboxes locally, they belong in the kit — every app charting a time series
-wants both.
-
-## SCOPE
-
-**A. A range picker for the toolbar slot.** Presets **1 day / 1 week / 1 month / 1 year** (operator,
-2026-08-04), emitting the selected range to the host. The host owns fetching; the picker owns the choice.
-
-The range must also carry the **granularity** the consumer should request — dcm ACT-1's query endpoint
-aggregates server-side, and a year of 4-hour buckets is ~2190 points, which no chart can render
-usefully. A picker that changes the window but not the resolution reproduces exactly the
-unreadable-density problem this WO exists to fix.
-
-**The range-to-resolution mapping (operator, 2026-08-04) — implement exactly this:**
-
-| Range | Resolution | Points |
-|---|---|---|
-| 1 day | 1 hour | 24 |
-| 1 week | 4 hours | ~42 |
-| 1 month | 1 day | ~30 |
-| 1 year | 1 month | 12 |
-
-Every preset lands between a dozen and fifty points, which is what keeps the chart readable at any
-range. **The resolution follows the window; it is not an independent control** and must not be exposed
-as one.
-
-
-**B. Series toggles for the toolbar slot.** Check/uncheck each series independently.
-
-**These are not cosmetic.** In jg's chart two series share one y-axis with different units — user counts
-reach 28 while presence-hours sit near zero, so the second series is invisible. Toggling one off
-rescales the axis and makes the other readable. Whether to offer a second y-axis instead is a real
-alternative: **if you do not add one, say so deliberately** rather than leaving it unconsidered.
-
-Deselecting every series must leave a stable empty chart — not a crash, not a permanent spinner.
-
-**C. Compose them into a preset** on `ChartFrame` + the existing `BarChart`, so a consumer gets frame,
-chart, picker and toggles from one component and passes data plus callbacks.
-
-**Presentational only — the host fetches.** Take `data`, the current range and series selection, and
-callbacks; do not call any endpoint. If all four hosts later write the identical fetch against ACT-1's
-endpoint, *that* is the signal to add an adapter — and note the inverse trap from this estate's recent
-history: building the shared thing before two identical consumers exist is how you generalise against a
-single case and get it wrong.
-
-## CONTEXT PACKAGE — verified current state (Orchestrator, Implementation map)
-
-Work from this package; do not explore broadly from scratch — open only the named files to verify.
-
-**New file: `src/components/charts/TimeSeriesChart.jsx`** (generic name — non-goal bars anything
-app-specific; this is not called `ActivityChart`). Export it in `src/index.js` right after the
-existing `LineChart` export (`:46`): `export { TimeSeriesChart } from './components/charts/TimeSeriesChart';`.
-
-**`ChartFrame`'s toolbar slot (`src/components/charts/ChartFrame.jsx`)** — the prop is named
-**`toolbar`** (not `toolbarSlot`), destructured `:20`, rendered `:74` inside a `Box` next to the
-title/subtitle, `justifyContent: 'space-between'`. Full prop list `:17-34`:
-`title, subtitle, toolbar, loading, error, isEmpty, emptyMessage, minHeight, aspect, exportOptions,
-onExportSvg, onExportPng, ariaLabel, children, variant, sx`. State precedence `:58-65`:
-`loading → error → isEmpty → children` — `TimeSeriesChart` passes its own `loading`/`error`/`isEmpty`
-straight through, it does not reimplement these.
-
-**`BarChart` (`src/components/charts/BarChart.jsx`, 44 lines)** — required props `xAxisLabel`/
-`yAxisLabel` (throws if absent, `:27-29`). `series` is a bare array of MUI X-Charts series objects,
-e.g. `{ data: [...], label, ... }` — no ucm wrapping. Colors: `palette || neutralPalette.categorical`
-(from `useNeutralChartPalette()`), assigned **positionally by index** — series `i` gets
-`categorical[i]`. `hideLegend={series.length <= 1}`.
-
-**Data contract for `TimeSeriesChart`** (design decision, state it): the host has already fetched
-and shaped the series (dcm ACT-1's query endpoint returns rolled-up buckets; this component knows
-nothing about that origin). Prop shape:
-```jsx
-<TimeSeriesChart
-  title
-  xAxisLabel
-  yAxisLabel
-  data={{ xLabels: [...], series: [{ key: 'users', label: 'Users', data: [...] }, { key: 'presence', label: 'Presence', data: [...] }] }}
-  loading
-  error
-  onRangeChange={(rangeKey, granularity) => {...}}   // rangeKey: '1d'|'1w'|'1m'|'1y'
-/>
-```
-Range selection is **self-managed internal state** (default a sensible preset, e.g. `'1w'`), emitting
-`onRangeChange(rangeKey, granularity)` on every change so the host can refetch `data` for the new
-window — the host owns fetching (non-goal), this component owns only which range is currently
-selected and telling the host what changed. Series-toggle visibility is **also self-managed internal
-state** (`Set` of visible series keys, all visible by default) — deselecting is a pure client-side
-filter over already-fetched `data`, no host round-trip needed, so no `onSeriesToggle` callback is
-required (optional to add if a reviewer disagrees, but the WO's own framing — "these are not
-cosmetic... toggling rescales the axis" — describes a display-only operation).
-
-**Range-to-granularity mapping — implement exactly, no per-app override:**
-`'1d' → 'hour'`, `'1w' → '4hour'`, `'1m' → 'day'`, `'1y' → 'month'` (match whatever granularity
-vocabulary dcm ACT-1's query endpoint expects once it publishes — since CHART-2 does not fetch, the
-exact string values are this component's own contract, name them clearly, e.g. `'hour' | '4hour' |
-'day' | 'month'`, and state the chosen vocabulary in the completion note so ACT-1/ACT-3 can align).
-
-**Range picker widget — decide and state (per WO's own "if you consider X, say so"):** this repo has
-**zero existing `ToggleButtonGroup` usage** (grepped, confirmed) but an established, deliberate
-`RadioGroup` + `FormControlLabel` convention for single-choice controls
-(`src/messaging/PollCard.jsx:1-140`, code comment there explains why: native arrow-key nav + grouped
-screen-reader announcement — "a bare ungrouped `Radio` per option... loses both"). Prefer
-`RadioGroup`/`FormControlLabel` to match this repo's convention unless a segmented-button visual is
-judged clearly better for a 4-preset picker — either is acceptable, but state which and why.
-
-**Series toggles — `Checkbox` + `FormControlLabel` per series**, matching this repo's established
-multi-choice pattern (`PollCard.jsx`'s multi-choice mode; also `Composer.jsx:181`,
-`ProfileComponent.jsx:232,244`). **Accessibility requirement, verified as a real gap**: colors from
-`getNeutralChartPalette` are assigned positionally with no name-to-color map and no shape
-differentiation (`src/components/charts/palette.js`, full file) — so each checkbox's `label` MUST be
-the series' text name (`FormControlLabel` gives this for free), not a bare colored swatch. Optionally
-also render a small colored swatch next to the label (matching the series' `BarChart` color at the
-same index) as a secondary, non-exclusive cue.
-
-**Second y-axis — decision required by the WO, make it explicitly:** `BarChart` already supports a
-dual-axis shape (`yAxisKey: 'secondary'` per series, paired with `yAxis={[{id:'primary'},
-{id:'secondary'}]}`), so it is technically available — but **do not use it here**. Scope B's series
-toggles are the WO's chosen, required fix for the shared-axis-different-units problem (jg's user
-counts vs. presence-hours); a second y-axis is the *alternative* the WO explicitly did not choose.
-State this decision plainly in the completion note — do not leave it to be inferred from absence.
-
-**Empty state — all series deselected:** `ChartFrame`'s `isEmpty` prop drives its own empty-state
-`Alert` (`:58-65`). When every series is toggled off, `TimeSeriesChart` must NOT pass an empty
-`series` array to `BarChart` (which would likely throw or render a blank axis) — instead set
-`isEmpty` truthy on `ChartFrame` and skip rendering `BarChart` entirely for that render, matching
-required test 3 ("stable empty chart: no crash, no spinner").
-
-**i18n — extend `src/i18n/chartsTranslations.ts` in place** (single `chartsTranslations` object,
-`<ComponentName>.<CONSTANT_KEY>` convention, all four `de/fr/en/sw`, `:1-38` for the existing shape
-to match). New keys needed: `TimeSeriesChart.RANGE_1_DAY`, `RANGE_1_WEEK`, `RANGE_1_MONTH`,
-`RANGE_1_YEAR`, and a label for the series-toggle group (e.g. `TimeSeriesChart.SERIES_LABEL`).
-
-**Tests — new `tests/TimeSeriesChart.test.jsx`**, matching `tests/ChartFrame.test.jsx`/
-`tests/BarChart.test.jsx` conventions (both fully precedent): `// @vitest-environment jsdom` header,
-vitest + `@testing-library/react`, `afterEach(cleanup)`, a minimal per-file `i18next.createInstance()`
-+ `I18nextProvider` (not the app's real i18n config), wrapped in `ThemeProvider theme={createTheme()}`.
-For test 1 (range emits granularity) and the series-filter tests, mock `@mui/x-charts/BarChart` itself
-via `vi.hoisted` + `vi.mock` to inspect exact props passed through (`BarChart.test.jsx`'s own pattern,
-`chartSpy.mock.calls[0][0]`) — do not mock ucm's own `BarChart`/`ChartFrame`, the point is testing the
-real composition.
-
-## NON-GOALS / DO NOT TOUCH
-- Do not fetch data, and do not import anything app-specific.
-- Do not change `ChartFrame`, `BarChart`, `LineChart` or the palette beyond what composing requires. If
-  `ChartFrame` lacks something, **extend it deliberately and say so** — do not work around it in the
-  preset.
-- Do not add a charting dependency; MUI X-Charts is already the kit's basis.
-- No persistence of the picker or toggle state — that is the host's decision.
-
-## RISKS
-- The toolbar slot has no consumer today, so this is its first real use. Expect to find gaps in it;
-  fixing them is in scope, working around them is not.
-- Accessibility: the picker and checkboxes are controls, not decoration — labels, keyboard operation and
-  state must be right. Series colour alone must not be the only way to tell which toggle maps to which
-  series. `ui_reviewer` should check this specifically.
-- Every host inherits the preset; a visible behaviour change beyond jg.
-
-## REQUIRED TESTS TO WRITE
-Narrow and behavioural. Do NOT run the full suite.
-
-1. Selecting a range emits both the range **and** the mapped granularity to the callback — assert the
-   granularity, which is the half most likely to be dropped.
-2. Toggling a series off removes it from the rendered chart and leaves the others.
-3. Toggling **all** series off renders a stable empty chart: no crash, no spinner.
-4. The preset renders `ChartFrame`'s empty state for empty data, exactly once.
-
-**Non-vacuity:** test 1 must fail if only the range is emitted. Assert the emitted payload, not that a
-callback fired.
-
-## TEST SCOPE FOR THE GATE (orchestrator)
-The chart component tests. Not the full suite.
-
-## TARGET REPO
-`C:\Users\biglmi\Documents\webapps\ui-core-micha`. Branch `main` (or `develop` if present). Publish per
-the repo's release flow; consumer pin bumps are separate.
-
-## MINI-HANDOVER (pastable)
-
-> Repo: `C:\Users\biglmi\Documents\webapps\ui-core-micha` (branch `main`, or `develop` if present).
-> Work order: `work-orders/CHART-2.md` — read it fully, then follow the `orchestrate-codex` skill.
->
-> Extends CHART-1, whose `ChartFrame` already has an unused **toolbar slot** — that is where the range
-> picker and series toggles go. **Presentational only: the host fetches, this component takes data and
-> callbacks.**
->
-> The one thing most likely to be half-done: the range picker must emit a **granularity** alongside the
-> window. dcm ACT-1 aggregates server-side, and a 1-year range at 4-hour buckets is ~2190 points — a
-> picker that widens the window without coarsening the resolution reproduces the unreadable chart this
-> WO exists to fix. Test 1 asserts the granularity for that reason.
->
-> The series toggles are a real fix, not a preference: jg's two series share one y-axis with different
-> units, which is why one of them is invisible today. If you consider a second y-axis instead, decide
-> deliberately and say so.
-
-## PROGRESS CONTRACT
-Emit `PLAN: <steps>` up front, then a single-line `PROGRESS: [<n>/<total>] <action>` before every
-relevant action and `PROGRESS: [<n>/<total>] done` on completion, spaced so no gap exceeds ~2 min,
-stdout unbuffered, and exactly one final `RESULT: DONE|BLOCKED <reason>`.

package/work-orders/CHART-3.md

@@ -1,163 +0,0 @@
-# WORK ORDER CHART-3 (ui-core-micha) — fix TimeSeriesChart rendering nothing on async data load
-
-**EXECUTION DIRECTIVE.** If you are the implementer reading this as your own spec, this section is not
-addressed to you — it tells the Orchestrator how to invoke you; you ARE that invocation, do not shell
-out to `codex exec`. Orchestrator: 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`, prompt passed as a positional argument from this
-file. Fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit.
-
-Bug-fix WO on the landed CHART-2. Found live in jg-ferien's "Aktivität" screen (ACT-3 consumer): the
-toolbar (range picker + series checkboxes) renders correctly, but the chart body never appears —
-`ChartFrame`'s empty-state `Alert` shows permanently, even once real data has loaded.
-
-## TIER
-Tier 2 — shared-core UI consumed by every app that adopts `TimeSeriesChart`.
-Independent `reviewer` + `ui_reviewer` mandatory.
-
-## WHY
-
-`TimeSeriesChart` initializes `visibleKeys` via a **lazy `useState` initializer** that reads
-`seriesConfig` (derived from the `data` prop) only once, at first mount:
-
-```js
-const [visibleKeys, setVisibleKeys] = useState(
-  () => new Set(seriesConfig.map((series) => series.key)),
-);
-```
-
-jg-ferien's `ActivitySection.jsx` mounts `TimeSeriesChart` with `data = { xLabels: [], series: [] }`
-(its own initial `useState`), then fetches asynchronously in a `useEffect` and updates `data` only
-once the API call resolves — the standard "mount empty, fill later" pattern. Because the lazy
-initializer never re-runs on prop updates, `visibleKeys` stays a permanently empty `Set` even after
-real series arrive. Downstream:
-
-```js
-const visibleSeries = seriesConfig.filter((series) => visibleKeys.has(series.key)); // always []
-const isDataEmpty = seriesConfig.length === 0 || visibleSeries.length === 0;        // always true
-```
-
-`isDataEmpty` is permanently `true`, so `ChartFrame` renders its empty-state `Alert` forever, no
-matter how much data loads. The toolbar renders fine because the range picker and the series
-checkboxes are driven directly off the live `seriesConfig`, not off `visibleKeys` — only the chart
-body is gated on the stale set. This reproduces on every host that fetches asynchronously after
-mount (the overwhelmingly common case), not just jg-ferien.
-
-## SCOPE
-
-**Fix `visibleKeys` to track newly-appeared series without discarding a user's manual toggle.**
-
-Required behaviour:
-1. When `data`/`seriesConfig` changes and introduces a series key not seen before, that key must
-   become visible by default (matches current first-mount behaviour, just not mount-only).
-2. A series key the user has manually toggled off must **stay off** across a range change that
-   still includes that key (e.g. don't reset all toggles to "all visible" on every `data` update —
-   that would silently undo the user's own toggle, a second bug of the opposite kind).
-3. A key that disappears from `seriesConfig` (e.g. a range change that drops a series) and later
-   reappears is treated as new for step 1 (simplest correct behaviour; do not attempt to remember
-   toggle state for absent keys unless it falls out naturally from the fix).
-
-This is a "seen this key before, default it visible; otherwise respect the user's own toggle" sync,
-not a full rewrite of the toggle model — `toggleSeries`, the checkbox rendering, and the empty-state
-logic in SCOPE stay as they are; only the initialization/sync of `visibleKeys` changes.
-
-## NON-GOALS / DO NOT TOUCH
-- Do not change `ChartFrame`, `BarChart`, `LineChart`, or the palette.
-- Do not change the range-picker or the range-to-granularity mapping (`RANGE_OPTIONS`).
-- Do not add an `onSeriesToggle` callback or any other new prop/API surface — this is a bug fix
-  within the existing component contract, not a scope extension.
-- Do not touch `chartsTranslations.ts` — this WO is unrelated to i18n (a separate, already-diagnosed
-  issue in a different repo is being fixed independently).
-
-## RISKS
-- The fix must not reintroduce the mount-time bug in a different form (e.g. resetting on every
-  render, or resetting on every `data` change including in-place mutations of the same series set —
-  that would silently discard the user's manual toggles on every range change, which is the
-  behaviour test 2 below exists to catch).
-- Every host that has adopted `TimeSeriesChart` since CHART-2 shipped is affected by this fix
-  (currently only jg-ferien via ACT-3); this changes rendering behaviour for all of them, in the
-  correct direction (chart now actually renders).
-
-## REQUIRED TESTS TO WRITE
-Narrow and behavioural, extending `tests/TimeSeriesChart.test.jsx`. Do NOT run the full suite.
-
-1. **Regression test for this exact bug**: mount `TimeSeriesChart` with empty `data`
-   (`{ xLabels: [], series: [] }`), then rerender with populated `data` (real `xLabels`/`series`) —
-   assert the chart body renders (not `ChartFrame`'s empty state), i.e. `isEmpty` becomes `false`
-   and `BarChart` receives the new series. This must fail against the current code and pass after
-   the fix — it is the non-vacuity check for this WO.
-2. **Toggle persistence across a data update**: toggle one series off, then rerender with updated
-   `data` that still contains that series key (e.g. a value change, same keys) — assert that series
-   is still filtered out (the user's manual toggle was not reset by the data update).
-3. **New series key appearing later defaults to visible**: mount with one series, rerender with a
-   second series key added — assert the new key is visible by default while any prior manual toggle
-   on the first key is preserved.
-
-**Non-vacuity:** test 1 must fail against the current `visibleKeys` lazy-initializer code (verify
-this before considering the fix complete) — it is reproducing the exact live bug from jg-ferien.
-
-## CONTEXT PACKAGE — verified current state (Orchestrator, Implementation map)
-
-Work from this package; do not explore broadly from scratch — open only the named files to verify.
-
-**File to change: `src/components/charts/TimeSeriesChart.jsx`.**
-
-Current state (verified, full relevant slice):
-```js
-const seriesConfig = data?.series || [];
-
-const [range, setRange] = useState(defaultRange);
-// Series identity (keys) is assumed stable for a given chart instance — the
-// toggle set is initialized once from the first data the chart receives.
-const [visibleKeys, setVisibleKeys] = useState(
-  () => new Set(seriesConfig.map((series) => series.key)),
-);
-```
-(`TimeSeriesChart.jsx:52-59`) — the comment above `visibleKeys` states the now-disproven assumption
-("series identity is stable for a given chart instance") that this WO corrects; update or remove it
-to match the new behaviour.
-
-`toggleSeries` (`:68-75`), `visibleSeries`/`visiblePalette`/`isDataEmpty` derivation (`:77-84`), and
-the checkbox rendering (`:103-123`) are all downstream of `visibleKeys` and should not need changes
-— only how `visibleKeys` is initialized/kept in sync with `seriesConfig` changes.
-
-**Suggested shape (not prescriptive — implement whatever satisfies SCOPE correctly):** replace the
-lazy `useState` with a `useEffect` keyed on the set of series keys in `seriesConfig`, that adds any
-newly-seen key to `visibleKeys` (defaulting it visible) without touching keys already present in the
-set — e.g. track previously-seen keys in a ref to detect "new" vs "toggled off", since a key
-present in both old and new `seriesConfig` but absent from `visibleKeys` must stay absent (it was a
-deliberate user toggle-off, not a fresh key). Keep `visibleKeys`'s existing `Set`-of-keys shape,
-`toggleSeries`'s update pattern, and the checkbox/empty-state code untouched.
-
-**Test file to extend: `tests/TimeSeriesChart.test.jsx`** — matches `tests/ChartFrame.test.jsx`/
-`tests/BarChart.test.jsx` conventions: `// @vitest-environment jsdom` header, vitest +
-`@testing-library/react`, `afterEach(cleanup)`, a minimal per-file `i18next.createInstance()` +
-`I18nextProvider`, wrapped in `ThemeProvider theme={createTheme()}`. Use `rerender()` from
-`@testing-library/react`'s `render()` return value to simulate the host updating `data` after mount
-(this is the exact scenario CHART-2's own tests never covered — they only mounted once with
-synchronous populated data).
-
-## TARGET REPO
-`C:\Users\biglmi\Documents\webapps\ui-core-micha`. Branch `main`. Publish per the repo's release
-flow (patch bump — bug fix, no interface change); consumer pin bumps are separate, out of scope.
-
-## TEST SCOPE FOR THE GATE (orchestrator)
-`tests/TimeSeriesChart.test.jsx` only. Not the full suite.
-
-## MINI-HANDOVER (pastable)
-
-> Repo: `C:\Users\biglmi\Documents\webapps\ui-core-micha` (branch `main`).
-> Work order: `work-orders/CHART-3.md` — read it fully, then follow the `orchestrate-codex` skill.
->
-> Bug fix on CHART-2's `TimeSeriesChart`: `visibleKeys` is initialized once via a lazy `useState`
-> from whatever `data` is at first mount, so any host that fetches asynchronously after mount (the
-> normal case) ends up with a permanently-empty `visibleKeys` and the chart body never renders —
-> `ChartFrame`'s empty state shows forever even once real data arrives. Fix the sync so newly-seen
-> series keys default to visible while a user's manual toggle-off on an already-seen key survives a
-> data update. Regression test 1 is the non-vacuity check — verify it fails against current code
-> first.
-
-## PROGRESS CONTRACT
-Emit `PLAN: <steps>` up front, then a single-line `PROGRESS: [<n>/<total>] <action>` before every
-relevant action and `PROGRESS: [<n>/<total>] done` on completion, spaced so no gap exceeds ~2 min,
-stdout unbuffered, and exactly one final `RESULT: DONE|BLOCKED <reason>`.

package/work-orders/CHART-4.md

@@ -1,203 +0,0 @@
-# WORK ORDER CHART-4 (ui-core-micha) — TimeSeriesChart renders no chart body (zero height)
-
-**EXECUTION DIRECTIVE.** If you are the implementer reading this as your own spec, this section is not
-addressed to you — it tells the Orchestrator how to invoke you; you ARE that invocation, do not shell
-out to `codex exec`. Orchestrator: 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`, prompt passed as a positional argument from this
-file. Fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit.
-**Known at WO authoring time: the Codex workspace is out of credits for this session — the fallback
-applies immediately, do not spend time retrying `codex exec` first.**
-
-Bug-fix WO on CHART-2/CHART-3. Found live in jg-ferien's "Aktivität" screen (ACT-3/ACT-5 consumer)
-immediately after CHART-3 shipped and jg's pin was bumped: the toolbar, series checkboxes, and MUI
-X-Charts **legend** now all render correctly (proving CHART-3's fix works and real data is present),
-but the chart canvas itself — bars and axes — is entirely absent. The card ends right after the
-legend row with visible empty space beneath it.
-
-## TIER
-Tier 2 — shared-core UI consumed by every app that adopts `TimeSeriesChart`.
-Independent `reviewer` + `ui_reviewer` mandatory.
-
-## WHY
-
-`TimeSeriesChart` composes `ChartFrame` + `BarChart` but never supplies either with a height:
-
-```jsx
-<ChartFrame title={title} subtitle={subtitle} toolbar={toolbar} loading={loading} error={error} isEmpty={isDataEmpty}>
-  {!isDataEmpty && (
-    <BarChart xAxisLabel={xAxisLabel} yAxisLabel={yAxisLabel} xAxis={[{ data: data?.xLabels || [] }]}
-      series={visibleSeries.map(...)} palette={visiblePalette} />
-  )}
-</ChartFrame>
-```
-
-Neither `minHeight`/`aspect` (ChartFrame's own sizing props) nor `minHeight`/`aspect`/a raw MUI
-`height` (BarChart's) are passed. `ChartFrame`'s inner content `Box` has `display: flex, alignItems:
-center, justifyContent: center` with no defined height — with `alignItems: center` (not `stretch`),
-a flex child gets its own intrinsic height, not the parent's. `BarChart`'s own wrapping `Box` (`sx:
-{width:'100%', minHeight, aspectRatio}`) therefore also has no height when neither prop is supplied.
-MUI X-Charts' internal responsive container measures its actual parent height via `ResizeObserver` to
-size the SVG — with a zero-height parent, the chart canvas (bars, axes) renders at zero size. The
-**legend** is a separate MUI X-Charts sub-component sized by its own content (text + swatches), so it
-renders regardless of container height — which is exactly why the legend was the only visible sign
-of a mounted chart in the live screenshot.
-
-This gap was invisible until now because CHART-3's own bug (`visibleKeys` never populating) kept
-`isDataEmpty` permanently `true`, so `BarChart` never actually mounted in any live deployment before
-today. It also went uncaught by CHART-2's and CHART-3's own tests: both `tests/BarChart.test.jsx` and
-`tests/TimeSeriesChart.test.jsx` mock `@mui/x-charts/BarChart` itself (`vi.mock('@mui/x-charts/BarChart', ...)`
-per CHART-2's own required-tests convention), so no test in this repo has ever mounted the *real* MUI
-chart and observed its rendered size. The working reference is `dev/entries.jsx`'s `BarChartEntry`
-(DX-1 harness), which explicitly sets `minHeight={360}` on `ChartFrame` and `height={320}` directly
-on `BarChart` — i.e. every other real consumer of these primitives in this repo already knows it must
-supply a height; `TimeSeriesChart`, as a preset built on top, was supposed to supply this itself
-(hosts don't see `ChartFrame`/`BarChart` directly through the preset) and doesn't.
-
-## SCOPE
-
-**Give `TimeSeriesChart` a sensible built-in height for the chart it composes**, matching the
-DX-1-proven working pattern:
-1. Pass `minHeight` to `ChartFrame` (sizes the loading/error/empty states too, not just the chart).
-2. Pass a height down to `BarChart` so the actual MUI chart canvas gets a real, non-zero pixel size —
-   either `BarChart`'s own `minHeight`/`aspect` wrapper props, or a raw `height` forwarded via
-   `BarChart`'s `...chartProps` pass-through to `MuiBarChart` (the mechanism `dev/entries.jsx` uses
-   directly against `BarChart`, confirmed working there). Pick whichever actually renders a non-zero
-   chart canvas when verified (see REQUIRED TESTS) — do not assume `aspectRatio` CSS alone reliably
-   drives MUI X-Charts' `ResizeObserver` sizing without checking; the raw `height` prop is the
-   confirmed-working mechanism in this repo's own reference usage and is the safer default if there
-   is any doubt.
-3. Pick one fixed value (e.g. `320`/`360`, matching `dev/entries.jsx`'s own numbers) as a preset
-   default — this is a preset, not a raw primitive; the host does not choose chart height, matching
-   `TimeSeriesChart`'s existing "no new props" presentational contract. Do not add a new prop for
-   this unless a reviewer specifically asks for one.
-
-**This WO's real fix is the test gap, not just the pixels.** The reason this shipped broken twice is
-that every test in this file mocks the real MUI chart component. Required test 1 below must exercise
-the **unmocked** `@mui/x-charts/BarChart` and assert a real rendered size — a mocked-chart test would
-be exactly the kind of vacuous coverage that let this ship.
-
-## NON-GOALS / DO NOT TOUCH
-- Do not change the range picker, series toggles, `chartsTranslations`, or the CHART-3 `visibleKeys`
-  sync logic — this WO is scoped to sizing only.
-- Do not change `ChartFrame`'s or `BarChart`'s own prop contracts (`minHeight`/`aspect` already exist
-  on both) — only how `TimeSeriesChart` calls them.
-- Do not add a new prop to `TimeSeriesChart`'s public API for this — see SCOPE point 3.
-
-## RISKS
-- Every host that has adopted `TimeSeriesChart` is affected (currently jg-ferien via ACT-3/ACT-5) —
-  this changes rendering behaviour for all of them, in the correct direction (chart canvas now
-  actually visible).
-- Getting this wrong a second time (e.g. an `aspectRatio`-only fix that still doesn't reliably drive
-  MUI X-Charts' internal measurement) ships a third silent failure in the same component. The
-  required unmocked-render test exists specifically to catch that before it reaches a live app again.
-
-## REQUIRED TESTS TO WRITE
-Extend `tests/TimeSeriesChart.test.jsx`. Do NOT run the full suite.
-
-1. **The real bug's mechanism, not a jsdom layout measurement.** An initial attempt at this WO wrote
-   an *unmocked* test (real `@mui/x-charts/BarChart`, no `vi.mock`) asserting the rendered chart
-   surface's `viewBox` height was non-zero — verified, in practice, to be **vacuous**: it stayed green
-   even with the pre-fix code (no `height` prop anywhere), because jsdom's `ResizeObserver`/layout
-   handling does not reproduce the real-browser zero-height-parent behaviour this bug depends on. Do
-   not repeat that approach. Instead, keep the existing `chartSpy` mock convention (`vi.hoisted` +
-   `vi.mock('@mui/x-charts/BarChart', ...)`, already at `tests/TimeSeriesChart.test.jsx:9-10`) and
-   assert directly on the props the real `MuiBarChart` receives: `chartSpy.mock.calls.at(-1)[0].height`
-   must be a real, non-zero number. This is what actually distinguishes fixed from broken — confirmed
-   by reverting the fix and re-running: the prop assertion fails pre-fix (`props.height` is
-   `undefined`), the unmocked viewBox assertion does not.
-2. **Non-vacuity**: this test must fail against the current (pre-fix) code — verify before considering
-   the fix complete (see note above — already verified once for the prop-assertion approach).
-3. Existing mocked-`BarChart` tests (range/toggle/empty-state behaviour) stay as they are.
-
-## CONTEXT PACKAGE — verified current state (Orchestrator, Implementation map)
-
-Work from this package; do not explore broadly from scratch — open only the named files to verify.
-
-**File to change: `src/components/charts/TimeSeriesChart.jsx`.**
-
-Current return statement (verified, full slice, `:150-169`):
-```jsx
-return (
-  <ChartFrame
-    title={title}
-    subtitle={subtitle}
-    toolbar={toolbar}
-    loading={loading}
-    error={error}
-    isEmpty={isDataEmpty}
-  >
-    {!isDataEmpty && (
-      <BarChart
-        xAxisLabel={xAxisLabel}
-        yAxisLabel={yAxisLabel}
-        xAxis={[{ data: data?.xLabels || [] }]}
-        series={visibleSeries.map((series) => ({ data: series.data, label: series.label }))}
-        palette={visiblePalette}
-      />
-    )}
-  </ChartFrame>
-);
-```
-
-**Reference (working) pattern — `dev/entries.jsx:35-39`:**
-```jsx
-function BarChartEntry() {
-  return (
-    <ChartFrame title="Monthly cases" subtitle="Standalone BarChart entry" minHeight={360}>
-      <BarChart {...barChartFixture} xAxisLabel="Month" yAxisLabel="Cases" height={320} />
-    </ChartFrame>
-  );
-}
-```
-Note `height={320}` on `BarChart` here is NOT `BarChart`'s own `minHeight`/`aspect` wrapper prop — it
-lands in `BarChart`'s `...chartProps` rest spread (`BarChart.jsx:24,34`) and is forwarded straight to
-`MuiBarChart`'s own native `height` prop, which MUI X-Charts uses as a fixed pixel height instead of
-measuring the parent via `ResizeObserver`. This is the confirmed-working mechanism in this repo.
-
-**`ChartFrame.jsx:86-99`** — the content `Box`: `sx={{ width:'100%', minHeight, aspectRatio: aspect,
-display:'flex', alignItems:'center', justifyContent:'center' }}`. `alignItems:'center'` means a flex
-child (here, `BarChart`'s own `Box`) is NOT stretched to fill this Box's height — it keeps its own
-intrinsic height. Passing `minHeight` to `ChartFrame` sizes this outer Box correctly for the
-loading/error/empty `Alert`/`CircularProgress` states (which have no fixed height of their own and
-DO benefit from the flex-centered parent height), but does **not**, by itself, give `BarChart`'s
-child `Box` any height — that must come from `BarChart` itself (its own `minHeight`/`aspect`, or the
-raw `height` chartProp per the reference pattern above).
-
-**`BarChart.jsx:15-44`** — full file, already shown above in this WO's WHY section — `minHeight`/
-`aspect` are explicit named props (`:22-23`) applied to `BarChart`'s own wrapping `Box` (`:32`);
-anything else lands in `...chartProps` (`:24`) and is spread onto `MuiBarChart` directly (`:34`),
-which is how a raw `height` reaches the underlying MUI component.
-
-**Test file: `tests/TimeSeriesChart.test.jsx`** — already mocks `@mui/x-charts/BarChart` via
-`vi.hoisted` + `vi.mock` (`:9-10`) and every existing test reads `chartSpy.mock.calls.at(-1)[0]` to
-assert exact props (e.g. the `series`/`colors` assertions at `:87-89,94-99`). Add the new test in the
-same style, asserting `props.height` — see REQUIRED TESTS above for why an unmocked render test does
-NOT work here.
-
-## TARGET REPO
-`C:\Users\biglmi\Documents\webapps\ui-core-micha`. Branch `main`. Publish per the repo's release
-flow (patch bump — bug fix, no interface change).
-
-## TEST SCOPE FOR THE GATE (orchestrator)
-`tests/TimeSeriesChart.test.jsx`. Not the full suite.
-
-## MINI-HANDOVER (pastable)
-
-> Repo: `C:\Users\biglmi\Documents\webapps\ui-core-micha` (branch `main`).
-> Work order: `work-orders/CHART-4.md` — read it fully, then follow the `orchestrate-codex` skill.
-> **Codex workspace is out of credits this session — go straight to the direct-Claude fallback, do
-> not attempt `codex exec` first.**
->
-> Second bug in `TimeSeriesChart` (after CHART-3): the chart legend renders but the actual bars/axes
-> never appear because neither `ChartFrame` nor `BarChart` ever receive a height — MUI X-Charts'
-> responsive container measures a zero-height parent and draws nothing. `dev/entries.jsx`'s
-> `BarChartEntry` is the proof this is fixable: `minHeight={360}` on `ChartFrame` + `height={320}`
-> forwarded straight to `BarChart` (MUI's own native height prop, not the wrapper's `minHeight`/
-> `aspect`). The required regression test must NOT mock `@mui/x-charts/BarChart` — every existing test
-> in this component mocks it, which is exactly how two sizing/rendering bugs shipped undetected.
-
-## PROGRESS CONTRACT
-Emit `PLAN: <steps>` up front, then a single-line `PROGRESS: [<n>/<total>] <action>` before every
-relevant action and `PROGRESS: [<n>/<total>] done` on completion, spaced so no gap exceeds ~2 min,
-stdout unbuffered, and exactly one final `RESULT: DONE|BLOCKED <reason>`.