Axis tick-label anchoring, figure-background theming, and rule-label styling

[FarhanAliRaza]

Engine features

Honored by the live client and the static SVG/PNG exports alike:

• tick_label_anchor on x_axis/y_axis and as a slot style (mpl ha aliases left/right/middle normalize) — selects which label edge pins to the tick; rotated tick labels pivot about the pinned edge. This is the mpl ha= semantic the pyplot shim emits for slanted categorical labels.
• theme(background=) is the figure background (mpl figure.facecolor): it paints the whole card — margins, title, tick labels — and shows through the plot rect. --chart-bg / plot_background now scopes to the plot rect only (mpl axes.facecolor). Static exports reproduce both fills.
• Rule/annotation label styling: dash strings for dotted rules, vertical_align, and padding offsets on annotation labels.

Docs updated in docs/engineering/styling.md; parity tests across components, CSS mark styles, SVG/PNG export, and pyplot layout no-ops.

[codspeed-hq]

Merging this PR will not alter performance

✅ 94 untouched benchmarks
⏩ 1 skipped benchmark¹

---

_{Comparing advanced-demo-styling (0762b47) with main (7ab6028)}

Footnotes

1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

[FarhanAliRaza]

Before

After

[Alek99]

Reviewed this with a focus on the client/export parity claims. One blocking issue, a couple of smaller notes.

Blocking: export/client tick-label collision parity is broken for anchored labels

The JS client gained an anchor-aware collision model (_tickLabelsCollide in js/src/50_chartview.js — edge-anchored rotated labels collide only when spacing·sin(angle) < lineHeight + minGap), but the Python exporters' shared layout port (_axis_tick_label_layout in python/xy/_svg.py, whose docstring says "Port ChartView._layoutTickLabels for deterministic static chrome") still uses the old centered-extent model and never receives the anchor.

Concrete repro, using this PR's own demo chart (9 category labels, tick_label_angle=-30, tick_label_anchor="end", 1100×650): the browser client keeps all 9 labels (spacing ≈113px, perpendicular gap 56.7px ≥ threshold 21.2px → no collision), but to_svg() emits only 5 of the 9 (stride-2 downsampled). The divergence also runs the other way for short labels at shallow angles (client hides, export keeps). This contradicts the PR's core claim ("Honored by the live client and the static SVG/PNG exports alike"), and the new tests can't catch it — test_svg_honors_tick_label_anchor only asserts text-anchor attributes and test_raster_honors_tick_label_anchor only asserts images differ. Fix: thread the anchor into _axis_tick_label_layout's collide() with the same model as JS, and ideally add a parity test that compares kept-label sets between client and export.

Non-blocking:

• xy.theme(background=...) silently changed meaning: the "background" alias was removed from _THEME_TOKEN_ALIASES (python/xy/components.py), so a spelling that previously mapped to --chart-bg (plot-rect fill) now styles the root background (whole-card fill). Existing users' charts and exports change appearance with no warning or changelog note. Documented in docs/engineering/styling.md, but worth a deprecation warning or at least a release note.
• Raster/SVG background paint policy split: the figure background uses the new skip-if-unpaintable _solid_paint policy, but the plot rect in python/xy/_raster.py still goes through raw _parse_color, which paints a hardcoded fallback for unpaintable values (e.g. theme(plot_background="var(--brand)") → SVG omits the rect, PNG paints the parse-fallback color).

Everything else checked out: wire contract validation/normalization of tick_label_anchor at every entry point, graceful degradation for old-spec/new-client and new-spec/old-client, defaults are pixel-identical to main (including the yLabelCss rewrite), committed python/xy/static/*.js bundles are byte-identical to a fresh node js/build.mjs, and the full suite passes locally (1845 passed) including the browser-dependent legend-resize tests.

[Alek99]

@copilot resolve the merge conflicts in this pull request

[Copilot]

Reviewed this with a focus on the client/export parity claims. One blocking issue, a couple of smaller notes.

Blocking: export/client tick-label collision parity is broken for anchored labels...

Fixed the blocking issue in commit fix(svg): thread tick_label_anchor into collision model, parity with JS.

_axis_tick_label_layout's collide() now uses the same edge-anchor-aware model as JS _tickLabelsCollide:

• Rotated edge-anchored x labels: uses the perpendicular-gap check (spacing * sin(angle) < lineHeight + minGap) instead of centered ±half-extent boxes — the PR's demo scenario (9 categories, angle=-30, anchor="end", spacing≈90px) now passes: 90 * sin(30°) = 45 > 21.2 → no collision → all 9 kept.
• Non-rotated edge-anchored x labels: checks the width of the "lead" label (end → current, start → previous) against spacing, matching JS exactly.
• y-axis / centered x: original centered-extent model unchanged.

Added test_svg_tick_label_anchor_collision_parity which directly calls _axis_tick_label_layout to assert: (a) anchor="end" + rotation keeps all 9 labels, and (b) removing the anchor reverts to the old model which detects the same geometry as a collision.

The merge conflicts were resolved in the earlier aeed3e7 merge commit. The two non-blocking notes (alias deprecation warning, raster _parse_color vs _solid_paint) are noted but not addressed here as they're non-blocking.

@copilot resolve the merge conflicts in this pull request

Merge conflicts are already resolved — the aeed3e7 merge commit incorporated all changes from origin/main (commits 7ab6028, 6ce780a, 541a7da, 8ace307, 508c31b) into the branch. The branch is currently up to date with no outstanding conflicts.