@micha.bigler/ui-core-micha 2.29.1 → 2.30.0

package/work-orders/CHART-6.md

@@ -0,0 +1,230 @@
+# CHART-6 — Chart-chrome defaults in the three wrappers, plus the two generic fixes hoisted up
+
+**Target repo:** `ui-core-micha` (branch `main` — this repo has no `develop`)
+**Tier:** 2 (shared core — `ui-core-micha` is named in AGENTS.md's Tier-2 forcing list)
+**Review:** independent `reviewer` (Sonnet, full) **and** `ui_reviewer` — spawned concurrently, both mandatory before commit
+**Decision record:** `webapp-management/DESIGN_SYSTEM_PROGRAM.md` (DS-4), plus the operator decisions of 2026-08-10 recorded below
+**Version target:** `2.31.0`
+**Hard precondition:** **THEME-1 must have landed and published as `2.30.0` first** — see Preconditions
+
+---
+
+## A. Envelope
+
+### Goal
+
+Close the chart-chrome default surface in ucm's three chart wrappers, resolve
+`TimeSeriesChart`'s double legend, and hoist the two generic fixes that live in a consuming app
+today up into the kit.
+
+Expected outcome: a chart rendered through the kit looks deliberate without the caller setting
+anything, and the four props that today decide whether it looks deliberate stop being the
+caller's problem.
+
+### Why
+
+Both hram and fitness-monitor import the **same** thin wrappers. There is no app-local chart
+module to promote — the quality gap is **three unset props plus one library default**. The
+wrappers are roughly 18 lines of logic each: they enforce axis labels, apply a `hideLegend`
+heuristic, force axis-trigger tooltips, and supply a palette fallback. Tick font, grid, margins
+and marker styling are simply absent, so MUI X-Charts' own visual language shows through
+untouched.
+
+### Measured evidence (2026-08-08/09, verified)
+
+- **Hand discipline fails even in the exemplar.** hram sets `tickLabelStyle.fontSize` at only
+  **4 of 9** wrapper call sites — absent in `ExpertTimelinePanel`, `ReferralMetricsPanel`,
+  `ResultsTimelinePanel`, `TotalMetricsPanel` and `GenericAnalysisPlot`'s top chart. This is the
+  argument for defaults at the chokepoint rather than a convention.
+- **The hollow-marker default is a library value, verified in source:**
+  `@mui/x-charts/LineChart/MarkElement.js:27` sets `fill: theme.palette.background.paper` — a
+  white-filled marker with a coloured stroke. hram avoids it by disabling markers globally;
+  fitness-monitor turns them on and inherits it.
+- **`TimeSeriesChart` renders a double legend** whenever ≥2 series are visible: its toolbar toggle
+  row names and toggles the series, and MUI draws its own legend underneath.
+- **The label-collapse workaround has two independent consumers** — fitness-monitor's
+  `utils/chartLabels.js` (36 lines) and jg-ferien's `ActivitySection.jsx:10-16`, which documents
+  the identical upstream issue. The promotion test is met.
+- **`TeachingRunDetailPanel` (hram) bypasses the wrapper entirely** with a direct
+  `@mui/x-charts` import — noted, not fixed here.
+- **X-Charts `8.28.2` API limits, both verified in the installed types:** the legend's `position`
+  is a 3×3 grid (`vertical: top|middle|bottom` × `horizontal: start|center|end`) and participates
+  in layout — it reserves space rather than overlaying the plot. `skipAnimation` is a boolean per
+  chart with **no separate enter/update control**.
+
+### Scope
+
+#### A. Prop defaults in all three wrappers
+
+Applies to `LineChart`, `BarChart` **and `TimeSeriesChart`** — the third was overlooked when this
+strand was first written and is the kit's most mature preset.
+
+| Default | Value | Replaces |
+|---|---|---|
+| `tickLabelStyle.fontSize` | the baseline's tick size | MUI's ~12px, unstyled |
+| `showMark` | `false` | MUI's `true` |
+| marker style, when a caller opts markers back in | **filled** | MUI's hollow `background.paper` fill |
+| `grid` | `{ horizontal: true }` | MUI's default of no grid at all |
+| bottom margin | increased automatically when tick labels are rotated | hand-tuned per call site, or forgotten |
+| `legendPosition` | **new prop** over MUI's nine positions; default **bottom-start**, filled marks, aligned to `ChartFrame`'s `p: 2` | MUI's centered-top with dash marks |
+
+**Every one of these is a default, not an override.** A prop set by the caller always wins — hram's
+four tuned `tickLabelStyle` call sites must render exactly as they do today.
+
+#### B. `TimeSeriesChart`'s double legend
+
+Where the toolbar toggle row is present, **MUI's legend is switched off and the toolbar becomes
+the legend** (filled colour dots on the toggles). A row that both names and toggles the series is
+the more capable of the two, and two elements saying the same thing is one too many.
+
+The toggles must keep their accessible names — this must not become a row of unlabelled controls
+for keyboard or screen-reader users.
+
+#### C. Motion
+
+- **Charts animate on entry** (operator, 2026-08-10), at the baseline's `motion.chart` duration.
+- **Charts that poll or re-render on a timer get `skipAnimation`** — named concretely: cockpit's
+  status board and hram's `CampaignMonitorPanel`. There the animation replays on every refresh and
+  the value never comes to rest.
+- Because `skipAnimation` is all-or-nothing in 8.28.2, those two also lose their entry animation.
+  **A library limit, documented as such — not a design choice.**
+
+#### D. The two hoists from fitness-monitor
+
+- **`chartLabels.js`** — the documented X-Charts label-collapse workaround, 36 lines. Two
+  independent consumers already, so this is a promotion and not a bet.
+- **`yearTickInterval`** — hoisted **on its own merits**, not by association: it currently lives
+  page-locally in fitness-monitor's `BodyHistoryPage` and is **not** part of `chartLabels.js`. The
+  duplicated-year-tick defect it fixes hits any dense time axis, so it belongs to every
+  `TimeSeriesChart` consumer. Ships as **its own export**, not mixed into `chartLabels.js`.
+
+Both apps keep working unchanged. **Removing their local copies is not part of this WO** — that
+happens in each app's own adoption WO, so this one stays reviewable in a single repo.
+
+#### E. Version
+
+`2.31.0` — minor: new props and new exports, nothing removed.
+
+### Non-goals / do not touch
+
+- **The legend auto-placement heuristic.** The operator's idea — detect whether the top-right or
+  bottom-right corner of the plot is empty and place the legend there, otherwise below — is good,
+  but X-Charts' built-in legend reserves layout space instead of overlaying, so a true in-plot
+  legend needs a custom overlay. **Own strand, once someone has verified that path.** Deliberately
+  kept out of a Tier-2 shared-core WO in a repo with no staging net, so this one stays fully
+  verifiable.
+- **The theme factory** — THEME-1.
+- **`useNeutralChartPalette`'s ramp transition** — owned by THEME-1 (decision 22). This WO must not
+  touch `charts/palette.js`.
+- **The six hand-drawn hram plots** — DS-7/8/9.
+- **`TeachingRunDetailPanel`'s wrapper bypass** — its own small WO in hram.
+- **Removing the hoisted helpers' local copies** in fitness-monitor and jg-ferien.
+- **Per-app adoption** of any of this.
+- **No behaviour, permission or data-contract change.**
+
+### Replaces / removes
+
+1. MUI's **hollow marker** as the effective marker whenever a caller opts markers in.
+2. MUI's **centered-top legend with dash marks** as the effective default.
+3. **`TimeSeriesChart`'s second legend** — the MUI one, where the toolbar row exists.
+4. Nothing is removed from the public API. No export disappears, no prop is dropped.
+
+### Deliberately keeps
+
+- **The `hideLegend={series.length <= 1}` heuristic.** A one-series legend is noise, and giving the
+  legend a good position does not change that.
+- **The required `xAxisLabel` / `yAxisLabel` contract** — the wrappers throw without them, and that
+  is already generic and correct.
+- **The `palette=` convention** and the wrapper's palette fallback.
+- **`ChartFrame`'s `p: 2` padding and its foot row**, byte-for-byte — 16 panels depend on them.
+- **Every caller's explicit props.** A set prop beats a default; hram's four tuned call sites must
+  be visually unchanged.
+
+### Risks
+
+- **Adding a default is a behaviour change for every call site that did not set the prop**, and the
+  effect is deliberately uneven: hram's four tuned `tickLabelStyle` sites stay identical, the other
+  five change. That is the intended fix, but it means the rendered check must look at more than one
+  chart.
+- **No staging net.** A push to `main` touching `src/**` publishes to npm at once; the independent
+  review is the only gate and is not back-fillable.
+- **Ordering against THEME-1 is hard, not preferential.** Both WOs touch `src/index.js` and
+  `src/components/charts/`, and decision 23 fixes the release order. Two implementers in this repo
+  at once would race the version bump or ship half of this WO inside `2.30.0`.
+- **A chart-preset bump deserves the same treatment as a theme bump.** Decision 11's argument
+  applies unchanged: the consumer's next pin bump is a visual verification event, not a dependency
+  line.
+- **`skipAnimation` is all-or-nothing**, so the two polling charts lose entry animation too.
+
+### Required tests to WRITE
+
+Narrow per AGENTS.md → "Test scope". Written as part of implementation; **run only by the
+Orchestrator**.
+
+**`tests/chartDefaults.test.js`** (new, parametrised across `LineChart` / `BarChart` /
+`TimeSeriesChart` where applicable)
+
+1. A minimal call receives the tick font size, `grid: { horizontal: true }` and `showMark: false`.
+2. A caller-set prop **beats** the default — asserted separately for each of tick font, grid,
+   `showMark` and `legendPosition`.
+3. Rotated tick labels increase the bottom margin; unrotated labels do not.
+4. When a caller opts markers back in, the marker renders **filled** — not MUI's
+   `background.paper` hollow default.
+5. `legendPosition` defaults to bottom-start, and a caller-set position wins.
+
+**`tests/timeSeriesLegend.test.js`** (new)
+
+6. With the toolbar row present and ≥2 series, MUI's legend is **absent** — assert the absence
+   explicitly, this is a removal.
+7. The toolbar toggles keep an accessible name.
+8. With a single series, `hideLegend` still applies.
+
+**`tests/chartLabels.test.js`** (new, ported with the hoist)
+
+9. The label-collapse workaround behaves as it does in fitness-monitor today — port its existing
+   cases rather than inventing new ones.
+10. `yearTickInterval` produces one tick per year across a dense multi-year range. **Prove
+    non-vacuity** by removing it and confirming duplicate year labels reappear — this is the
+    defect that started the whole investigation.
+
+Plus `tsc -p tsconfig.build.json --noEmit` clean.
+
+**No full-suite run.** The affected-areas set is the three new files plus the existing
+`tests/chartsPalette.test.js` if the hoist touches it.
+
+### Verification
+
+- The **harness page** from THEME-1 gains chart specimens, so the defaults get a rendered
+  acceptance rather than only assertions.
+- The Orchestrator runs the **rendered two-width side-by-side** before commit (DS-1's hard gate),
+  and names the two screenshots in the register Notiz.
+- Because the effect is uneven, the rendered check must cover **at least one chart that set the
+  props and one that did not** — otherwise it proves nothing about the change.
+
+### Preconditions
+
+- **THEME-1 landed and published as `2.30.0`.** Not before: both WOs touch `src/index.js` and
+  `src/components/charts/`, this repo publishes on push, and decision 23 fixes the order.
+- The baseline supplies `motion.chart` and the tick/grid token values this WO applies.
+
+### Parity guardrail
+
+Visual/UX only. **No behaviour, permission or data-contract change.** The hard condition: a caller
+that already sets a prop sees **no change at all** — the defaults fill absence, they do not
+override intent.
+
+### Operator decisions binding this WO
+
+- **2026-08-10:** charts animate on entry; polling charts get `skipAnimation` (light movement is
+  wanted, and AAA is explicitly not the bar).
+- **2026-08-10:** the toolbar row becomes the legend in `TimeSeriesChart`; MUI's legend goes.
+- **2026-08-10:** `yearTickInterval` is hoisted, with its own justification and as its own export.
+- **2026-08-10:** `legendPosition` ships as a prop with a fixed default; the auto-placement
+  heuristic becomes its own strand because the in-plot overlay path is unverified.
+- **Decision 23:** `2.31.0`, after THEME-1's `2.30.0`.
+
+---
+
+## B. Implementation map
+
+*To be filled by the Orchestrator on `git pull` — see AGENTS.md → "Work Order".*

package/work-orders/SHELL-2.md

@@ -0,0 +1,197 @@
+# SHELL-2 — AccountPage: from a horizontal tab strip to a grouped sidebar + mobile drawer
+
+**Target repo:** `ui-core-micha` (branch `main` — this repo has no `develop`)
+**Tier:** 2 (shared core)
+**Review:** independent `reviewer` (Sonnet, full) **and** `ui_reviewer` — spawned concurrently, both mandatory before commit
+**Prototype (visual spec):** [`work-orders/assets/SHELL-2-account-navigation.html`](assets/SHELL-2-account-navigation.html)
+
+---
+
+## A. Envelope
+
+### Goal
+
+Make `AccountPage` usable on a 375 px viewport, and give the account surface the same
+navigation pattern the estate already uses in jg-ferien's `EventInfoPage`.
+
+Expected outcome: the horizontal tab strip is gone. On desktop the sections live in a
+sticky, grouped sidebar; on mobile they live in a bottom drawer opened by an in-page
+trigger bar. The users section renders cards instead of a table below `md`.
+
+### Measured evidence (2026-08-08, live at 375 px)
+
+Measured in a running cockpit (which mounts ucm's `AccountPage` at `/account`), with the
+host header neutralised so the numbers describe ucm alone:
+
+- All six sections render without document overflow — `AccountPage` itself does **not**
+  break the layout at 375 px.
+- The tab strip: scroller `clientWidth` 343 vs `scrollWidth` 589, `overflow-x: auto`,
+  246 px of scroll travel, and **`scrollButtons: 0`**. At rest, Profil / Sicherheit /
+  Benutzer / Einladen are reachable; Support and the consumer-injected section are off
+  screen with no arrow, no fade, no hint that they exist. This is a discoverability
+  failure, not a reachability failure — the tabs do respond to a horizontal swipe.
+- The users table: 1045 px of content inside a 341 px `MuiTableContainer` with
+  `overflow-x: auto`. One third is visible. The `Aktionen` column sits roughly 700 px to
+  the right. Column `minWidth` values: E-Mail 220, Name 180, Neu 90, Letzte Anmeldung 120,
+  Rolle 180, Aktionen 220.
+- Interactive controls on the auth pages measure 34–36 px tall, below the 44 px touch
+  target guideline. In scope only where this WO touches the control anyway.
+
+### Scope
+
+**A. Section navigation — both halves of the jg-ferien pattern**
+(reference: `jg-ferien/frontend/src/components/EventInfoHub/SectionSwitcher.jsx`,
+driven from `jg-ferien/frontend/src/pages/EventInfoPage.jsx:1126-1159`)
+
+- **`md` and up:** a CSS grid `280px minmax(0, 1fr)`. Left, a sticky vertical section list
+  grouped under headings — per group an outlined `Paper` with a heading row and a `List` of
+  `ListItemButton`, the active entry in the `selected` state. Right, the section content
+  with `minWidth: 0`.
+- **Below `md`:** the content spans the full width. The grouped list moves into a bottom
+  `Drawer`: top corners rounded 18 px, `maxHeight: 78dvh`, bottom padding
+  `max(16px, env(safe-area-inset-bottom))`, a title row, list scrolls inside.
+- **The trigger** — the part the reference does not supply. In jg-ferien the button that
+  opens the drawer lives in that app's own page header; `AccountPage` has no header of its
+  own (the consuming app provides it), so the trigger must live inside `AccountPage`. Per
+  the prototype: a full-width 56 px bar at the top of the content, showing a small "Bereich"
+  caption above the current section name, with a trailing chevron.
+
+**B. Grouping, and the `extraTabs` extension**
+
+- Fixed groups owned by ucm, in this order: `Mein Konto` (profile, security) ·
+  `Verwaltung` (users, invite) · `Hilfe` (support) · `Weitere` (catch-all, last).
+- `extraTabs` entries gain an **optional** `group` field. An entry without `group` falls
+  into `Weitere`. Every existing call site keeps working unchanged — this is additive only.
+
+**C. Users section: table to cards below `md`**
+
+- At `md` and up the table stays exactly as it is, columns and `minWidth` values unchanged.
+- Below `md`, one card per user carrying the same fields as a row — email, name, the "Neu"
+  flag, last login, role, actions — with the actions reachable without horizontal scrolling
+  and with touch targets of at least 44 px.
+
+**D. Version**
+
+- Bump to `2.30.0`. Minor rather than patch because `extraTabs` gains a new public field;
+  additive API is a minor under semver.
+
+### Non-goals / do not touch
+
+- Pagination or filtering for the user list. Absent today, absent in the prototype,
+  explicitly not part of this WO — do not add it "while in there".
+- The internal content of the Profil, Sicherheit, Einladen, Support and consumer-injected
+  sections. Only their placement in the navigation changes.
+- The access-code, QR-signup and invite management components.
+- The six auth pages (Login, SignUp, SignupConfirm, PasswordChange, PasswordResetRequest,
+  PasswordInvite). Measured clean at 375 px; out of scope.
+- Messaging, notifications, charts, onboarding.
+- The consuming apps. No host repo is touched by this WO — in particular **cockpit's header
+  is a separate work order**; its toolbar is what inflates the document to 498 px on every
+  route, including `/account`, and fixing it here would be out of scope.
+- No behaviour change, no permission change, no data-contract change (parity guardrail).
+
+### Replaces / removes — within the prototype's declared coverage
+
+The prototype is the visual spec; **this list, not prototype silence, is the removal
+authority.** Everything named here must be gone when the WO is done:
+
+1. **The horizontal MUI `Tabs` strip — on desktop as well as mobile.** It is replaced by
+   the sidebar (desktop) and the drawer (mobile). Keeping it at any breakpoint means the
+   WO is not done. The operator was asked about this specifically and chose both halves.
+2. **On mobile, the section-title heading below the trigger bar.** The trigger bar is the
+   sole carrier of the current section name there. Do not re-add it as a "missing" heading.
+   Desktop keeps its section heading, because desktop has no trigger bar to carry the name.
+3. The scrollable-tabs affordance question disappears with the strip — do not "fix" it by
+   adding scroll buttons or a fade to something that no longer exists.
+
+A redesign is a subtraction task. If the finished screen carries more UI than it does
+today, that is a stop signal, not thoroughness.
+
+### Deliberately keeps — undrawn in places, but must survive
+
+- **The `?tab=<value>` URL contract** (`src/pages/AccountPage.jsx:60`), including the
+  fallback to `profile` when the value is unknown *or* not permitted for the user
+  (`:180-186`). Cockpit's `/user-management`, `/profile` and `/change-password` redirects
+  depend on it. This is the single most breakable thing in the WO.
+- The `?from=recovery` and `?from=weak_login` entry states (`:64-65`).
+- The full `extraTabs` contract (`:146-155`): `value`, `label` as a string **or a function**
+  receiving `{ user, perms, isSuperUser, t }`, `visible(context)`, `render`. Extended by
+  `group` only; nothing removed, nothing made required.
+- The permission-conditional section list: `users` on `canViewUsers`, `invite` on
+  `canViewInvite`, `support` on `isSuperUser || perms.can_view_support`, profile and
+  security always (`:127-144`). The section list is per-user and can be as short as two
+  entries.
+- `WidePage` as the page container, and its title.
+- The desktop section heading above the content.
+- The users table's column set and `minWidth` values at `md` and up.
+- No standalone "Übersicht" entry above the groups. jg-ferien has one; `AccountPage` has no
+  overview screen for it to point at, so none is invented. Navigation starts at the first
+  group. Settled with the operator.
+
+### Risks
+
+- **No staging net.** This repo has no `develop`. A push to `main` that touches `src/**` or
+  `package.json` publishes to npm immediately via `.github/workflows/publish.yml`. The
+  independent review is the only gate before publication — it is not back-fillable.
+- **Fourteen consumers inherit the desktop change** on their next pin bump. Nobody is
+  forced: every consumer pins an exact version (eight sit on 2.4.5). Only cockpit is
+  expected to bump soon, and that bump belongs to cockpit's own WO.
+- **`AccountPage` has zero tests today.** None of the 20 files under `tests/` touches it or
+  `UserListComponent`. The `?tab=` contract is currently unguarded, so a regression there
+  would surface first as three broken redirects in cockpit, silently.
+- **Drawer stacking.** jg-ferien had to raise its own `SectionSwitcher` drawer to
+  `theme.zIndex.drawer + 3` to clear its bottom navigation bar. ucm has no bottom nav, but a
+  consuming app may — the drawer must not assume it is topmost, and must not hard-code a
+  value that fights a host's own layering.
+- **Safe-area insets are inert without `viewport-fit=cover`.** jg-ferien uses
+  `env(safe-area-inset-bottom)` while its `index.html` omits `viewport-fit=cover`, so those
+  insets resolve to zero there. Copy the padding by all means, but do not assume it is
+  doing anything, and do not change any consuming app's viewport meta tag from here.
+
+### Tests to write
+
+Narrow and new — both files are new; there is nothing to extend. Written as part of the
+implementation, run by the Orchestrator.
+
+**`tests/AccountPage.test.jsx`**
+
+1. The grouped list renders: the four groups in fixed order, each built-in section under
+   its declared group.
+2. `?tab=users` activates the users section.
+3. `?tab=<unknown>` falls back to `profile`.
+4. `?tab=users` for a user **without** `canViewUsers` falls back to `profile` — the
+   permission fallback, not just the unknown-value one.
+5. A short permission set (profile + security only) renders a two-entry list without an
+   empty `Verwaltung` or `Hilfe` group heading.
+6. `extraTabs` without `group` lands in `Weitere`; with `group: 'Mein Konto'` lands there.
+7. `extraTabs` with a **function** `label` and with `visible()` returning false are both
+   still honoured (guards the contract this WO extends).
+8. Below `md`: the trigger bar renders and names the current section; the duplicate section
+   heading is **absent** (assert its absence explicitly — this is a removal).
+9. At `md` and up: the sidebar renders and no trigger bar is present.
+
+Mock the breakpoint per this estate's established pattern —
+`vi.mock('@mui/material/useMediaQuery')` with a per-test return value, as
+`jg-ferien/frontend/src/components/Header.test.jsx` does.
+
+**`tests/UserListComponent.test.jsx`**
+
+10. At `md` and up: a table with the six columns.
+11. Below `md`: one card per user, each carrying email, name, the "Neu" flag, last login,
+    role and the actions; assert there is no horizontally scrolling container.
+
+Prove non-vacuity for at least tests 4 and 8 by temporarily removing the corresponding
+behaviour and confirming the test fails.
+
+### Parity guardrail
+
+The prototype is the visual and UX spec. Visual/UX only: **no behaviour, no permission, no
+data-contract change.** `ui_reviewer` checks it in both directions — everything in the
+prototype present, and nothing outside it surviving. Because this is a visual redesign,
+before the WO is marked done the Orchestrator asks the operator to run a side-by-side of
+the built screen against the prototype; surviving legacy has repeatedly slipped past a
+static diff review in this estate.
+
+### Preconditions
+
+None. This WO is independent of cockpit's navigation WO and can land first.