docs: cover common Vaadin 8 to 25 migration pitfalls

[peholmst]

Based on feedback from a production Vaadin 8 → 25 migration. Each item below caused real debugging time and was either missing from the docs or hard to find from the symptom.

Charts — series.getConfiguration() returns null

New Series and Configuration section. A series is linked to a Configuration only by addSeries()/setSeries(), so reading getConfiguration() before that throws NullPointerException, and setyAxis(YAxis) throws IllegalStateException.

The feedback reported this as a V25 breaking change. It isn't — AbstractSeries behaves identically in 24.9.7 and 25.0.0 — so it's documented as a Charts pitfall rather than in the Upgrading Guide. It still bites when migrating V8 chart code that configures series before adding them.

Security — form login

Warning against configuring form login with Spring Security's formLogin() instead of the configurer's loginView(), with the symptom (ERR_TOO_MANY_REDIRECTS / "Connection lost"), plus a short pointer from the VaadinWebSecurity migration steps in the Upgrading Guide.

Security — the ROLE_ prefix

New "Roles & the Role Prefix" section: why @RolesAllowed("ADMIN") matches ROLE_ADMIN, why User.roles() works but authorities() doesn't, a warning that a missing prefix fails silently, and GrantedAuthorityDefaults for changing it. GrantedAuthorityDefaults had no mentions in the docs before this.

Security — programmatic role checks

The feedback proposed documenting a static SecurityUtils helper. AuthenticationContext already does that job and, unlike a static helper, strips the configured prefix instead of hardcoding ROLE_. Extended the Security Utilities section with the conditional-nav-item example instead, plus a note that hiding a nav item isn't a security measure.

Upgrading — layout access denied

Quoted the actual message so it's searchable, and explained how to choose the annotation. Correcting the premise slightly: the framework message already suggests the annotations (verified in AnnotatedViewAccessChecker for both 25.0.0 and 25.3.0-beta3), so this is about findability. Also, the feedback's advice to always use @PermitAll is too narrow — the layout must be at least as permissive as the views it hosts.

Upgrading — no default theme

Two accuracy adjustments to the reported symptom: the app renders with minimal base styles, not raw HTML, and an app with no AppShellConfigurator still falls back to Aura. The trap is specifically having one without a @StyleSheet, which is the upgraded-app case.

Upgrading — keeping the upgrade scoped

Short subsection in the Overview on changing only what the breaking changes require, including a note that this is worth stating explicitly to AI coding assistants.

---

One feedback item is not addressed here: the primer returned by get_vaadin_primer shows VaadinSecurityConfigurer.apply(http), which does not exist — vaadin() is the only factory method. That is already fixed in the MCP server release currently in QA, and the endpoint URL isn't changing, so no docs change is needed.

Vale is clean on all three files (remaining alerts are pre-existing) and Asciidoctor reports no new structural warnings.

🤖 Generated with Claude Code

[github-actions]

Preview Deployment

This PR has been deployed for preview.

URL: https://docs-preview-pr-5997.fly.dev

Changed pages

Added content is highlighted in green; removed content is marked in red on each page.

• components/charts/configuration — modified, +37/-0 lines
• flow/security/enabling-security — modified, +52/-0 lines
• upgrading — modified, +21/-0 lines

Built from 88c4aed