docs: add a Building Apps guide on application-wide error handling

[peholmst]

Adds a how-to guide on application-wide error handling for Flow applications, and replaces the TODO in Protect Views that was waiting for it.

Part of #6292 (the security/protect-views.adoc#L291 TODO) and #6288 ("Application-wide error handling and recovery").

What's in the guide

New page: articles/building-apps/ui-basics/handle-errors.adoc (Handle Errors)

• Copy-paste example:

  • ErrorReporter logs each error with a short error ID and builds the user message, which includes the exception in development mode only.
  • ApplicationErrorHandler shows that message in a closable notification.
  • ErrorView replaces InternalServerError with a standalone, @AnonymousAllowed page.
  • ErrorHandlingConfig installs the handler for every session.

• What users see by default, in development vs. production mode, for listener exceptions, not-found routes, access-denied navigation, and exceptions thrown during navigation.

• Unexpected errors: guidance on what not to show users, error IDs, the null-UI case, an error handler that must never throw, unwrapping the cause chain, the exact-type error-view redirect that the default handler does, @ControllerAdvice not applying to Flow views, background threads, the internal error and session expired system messages, and monitoring.

• Navigation errors:

  • a custom not-found view, and why users denied access to a view also land on it;
  • an optional access-denied view, with @AccessDeniedErrorRouter for views that should stay hidden;
  • relaxing the VaadinSecurityConfigurer catch-all rule for typed or bookmarked URLs;
  • why the catch-all error view stays out of the main layout, and why it allows anonymous access.

  It also notes that the HTTP status an error view returns doesn't reach the browser on the initial page load (Status returned by HasErrorParameter#setErrorParameter is ignored. flow#13421).

• Exceptions from services:

  • a table of where to handle what, with user-facing exception types as an alternative for business rules;
  • method security's AccessDeniedException goes to the error handler, with a pointer to splitting the handler into per-exception handlers as it grows;
  • OptimisticLockingFailureException is caught in the view that saves.

Changes from external research

A second commit applies findings from the Vaadin forum, Martin Vysny's error-handling article, the Jmix and Error Window add-on approaches, Flow GitHub issues, and internal Slack threads in #flow-user.

• Catch-all ErrorView out of the main layout. Since MainLayout unresponsive after unhandled exception in afterNavigation() flow#22146, if the layout itself throws, Flow falls back to InternalServerError, which shows the exception message in production.
• One shared ErrorReporter for both the handler and the error view. In #flow-user, developers asked for one example that covers both error paths.
• Exception details in development mode only.
• An error handler that never throws. A throwing handler makes the browser show the internal-error system message instead.
• System messages, the HTTP status caveat, @ControllerAdvice, signal effects, and the two alternatives for larger applications.

Placement

Under UI Basics, after Show a Notification and the other UI how-tos (order 40):

• The guide is about how the UI reacts when something fails: notifications, error views, and the session error handler. Business Logic covers writing services and background jobs, not how views react to their exceptions.
• Views & Navigation would only fit the error-view part.
• The guide builds directly on Show a Notification, which already lives in UI Basics.

Overlap with #6320

#6320 also replaces the TODO in security/protect-views.adoc. This PR uses the same paragraph wording but changes its link from Custom Error Handling to the new guide. It also adds one sentence that points to the guide's section on access-denied navigation. Git can't merge the two edits to that line automatically, so whichever PR merges second gets a one-line conflict. To resolve it, keep this PR's version of the paragraph.

The guide also links to protect-services#testing-method-security, a section that #6320 adds. If this PR merges first, the link opens Protect Services but doesn't jump to the section until #6320 is merged.

Verification

• I checked every Vaadin API against the Vaadin MCP (get_java_symbol, 25.3). I also read the Flow 25.3.3 sources for DefaultErrorHandler, ErrorHandlerUtil, Router, InternalServerError, AbstractRouteNotFoundError, RouteAccessDeniedError, NavigationAccessControl, AnnotatedViewAccessChecker, UI.access(), and the error-target registry, and the Spring Security 7.1 sources for method-security denial.
• I compiled all the code snippets with javac, including the revised copy-paste classes and the system messages bean, together with minimal stubs (MainLayout, HomeView, ProposalService, …), against this repo's dependency classpath (Vaadin 25.4.0-alpha1, Spring Boot 4.1). They compile with no deprecation warnings. VaadinIcon.CLOSE_SMALL is deprecated, so the code uses VaadinIcon.CLOSE.
• Vale reports 0 errors, 0 warnings, and 0 suggestions on the new page.
• Asciidoctor parses both changed files without warnings. Every xref target file and anchor exists.
• I didn't run a full local DS Publisher build. The preview deployment covers it.

🤖 Generated with Claude Code

[github-actions]

Preview Deployment

This PR has been deployed for preview.

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

Changed pages

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

• building-apps/security/protect-views — modified, +1/-1 lines, 1 removal marker(s)
• building-apps/ui-basics/handle-errors — added, +534/-0 lines

Built from 373eebe