Show asset annotations in asset charts

[Flix6x]

Description

Asset annotations (and account annotations) are now shown in the asset chart. Motivation: the CommunityScheduler plugin writes "reason for interfering" alert annotations (projected breach / DSO restriction) on community assets, and those should be visible on the community asset's chart page.

Implemented for both chart renderers: the ECharts fast charts (the default since #2234 landed) and the Vega-Lite charts (the opt-out fallback). Behavior is the same in both:

• Annotations appear as a lightly shaded time band across all subcharts of the asset chart (shared x-scale keeps them aligned); bands are drawn behind the data.
• Hovering (or clicking, on touch) a time inside an annotation window darkens the band only in the hovered subchart and shows the annotation text below that subchart, in the gap between the datetime axis labels and the next subchart — without changing the chart layout on hover.
• The regular data tooltip keeps working everywhere, including inside annotation bands (annotation marks define no tooltip and sit below the data hit-area).
• Alert annotations get a warm warning hue; other types stay neutral gray (var(--gray) CSS-var pattern for theme safety). The annotation text is colored accordingly.
• Instant (zero-duration) annotations render as a thin vertical rule with an enlarged triangle marker at the top; hovering within one resolution bin of the instant highlights it and shows its text.
• New endpoint GET /api/v3_0/assets/<id>/chart_annotations, mirroring the sensor endpoint (clipping, wrapping and stacking via prepare_annotations_for_chart), including account annotations.
• Added changelog item in documentation/changelog.rst

Implementation notes:

• Vega-Lite: one shared named dataset (asset_<id>_annotations) feeds the annotation layers of every subchart; each subchart gets its own hover/pin params, which capture the time of the hovered/clicked datum (events bubble to the view level), and annotations highlight when that time falls in their window. This is what lets the annotation marks stay non-obtrusive below the data while still reacting to hover.
• ECharts (fast-chart.js): bands are markAreas and instant rules are markLines on the first series of each subplot, silent and behind the data. Hover/pin is driven from zrender mouse events: the pointer's pixel position identifies the hovered subplot (the linked axisPointer can't tell subplots apart) and converting it to the time domain identifies the annotation. Clicking pins the highlight (so touch users can reach the text); clicking again releases it. A fixed text strip below each subplot keeps the layout stable on hover. The replay ruler moved into the shared markLine builder so it coexists with instant-annotation rules.
• The screenshots live in the dedicated FlexMeasures/screenshots repo (this repo stays free of image blobs).

Look & Feel

ECharts fast charts (default mode)

Resting: light bands in all subcharts	Alert hovered: warm band darkens, colored text below that subchart

Data tooltip still works inside a band	Instant annotation (rule + marker), hover scoped to bottom subchart

Vega-Lite charts (fallback mode)

Resting: light bands in all subcharts	Pinned (click): band darkens in that subchart, text below it

Data tooltip still works inside a band	Hover scoped to bottom subchart	Instant annotation (rule + marker)

How to test

1. Create an asset with a couple of sensors_to_show subcharts and some data.
2. Add annotations, e.g. via POST /api/v3_0/assets/<id>/annotations (one with "type": "alert", one "label", and one with start == end).
3. Open the asset's Graphs page for a window covering the annotations: light bands appear in all subcharts; hover a time inside a band to darken it in that subchart and see the annotation text below it; hover data inside the band to confirm the data tooltip still shows; click to pin; hover near the instant annotation's rule/marker to see its text. Then flip the fast-charts toggle and repeat in the other renderer.
4. pytest flexmeasures/api/v3_0/tests/test_assets_api.py -k annotation covers the endpoint and the generated (Vega-Lite) chart specs (per-subchart layers, unique hover params).

Vega-Lite path verified end-to-end with a headless browser against the toy account (two subcharts: Prices, Power flows) with an alert band, a label band and an instant annotation: hover darkening scoped to the hovered subchart, data tooltip inside bands, annotation text in the axis gap with total SVG height unchanged (667px before/during/after hover), no console errors.

ECharts path verified with headless Chrome driving renderFastChart on a two-subplot chart with the same three annotations (16 scripted checks): resting/hover/pin opacities and per-type colors, hover darkening scoped to the hovered subplot, pin persists until released, instant-rule highlighting within one resolution bin, data tooltip inside bands, and container height constant across all states; no console errors.

Appendix: earlier iteration (tooltip-based)

The first iteration showed the annotation details in a tooltip on the band itself, which swallowed the data tooltip inside bands and was dropped in review.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LQFkeGxDwErydUV5ZmHmki
https://claude.ai/code/session_01HBYFTyXL1dLcqX6M76Av6e

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33644415 | 📁 Comparing b8d161e against latest (8c414da)

  🔍 Preview build  

21 files changed · + 3 added · ± 18 modified

+ Added

• _autosummary/flexmeasures.data.models.planning.devices.html
• _autosummary/flexmeasures.data.models.planning.soc_projection.html
• _autosummary/flexmeasures.data.schemas.scheduling.utils.html

± Modified

• changelog.html
• genindex.html
• http-routingtable.html
• py-modindex.html
• _autodoc/SOC_MAXIMA.html
• _autodoc/SOC_MINIMA.html
• _autodoc/SOC_TARGETS.html
• _autosummary/flexmeasures.api.v3_0.assets.html
• _autosummary/flexmeasures.data.models.charts.defaults.html
• _autosummary/flexmeasures.data.models.generic_assets.html
• and 8 more...

[Flix6x]

Updated now that #2234 (ECharts fast charts) landed on main:

• Merged origin/main (resolved conflicts in graphs.html and the changelog) — the branch is mergeable again.
• Ported the annotation viz to the ECharts fast charts (f7eb993f5), which are the default renderer since feat: use ECharts to have faster charts (and more interactive) #2234. Same design as the Vega-Lite version: bands/instant rules behind the data in every subchart, hover darkens + shows the text below the hovered subchart only, click pins, alert hue, data tooltip untouched. Details and fast-chart screenshots are in the updated PR description.
• The Vega-Lite implementation stays as-is for the fallback mode (the toggle).

Verified the ECharts path with headless Chrome driving renderFastChart on a two-subplot chart (16 scripted checks incl. hover scoping, pinning, instant tolerance, tooltip-inside-band, constant layout height); pytest -k annotation passes on the merged branch.