[peholmst]

Review risk: two-way door. Docs and examples only: three new how-to pages, seven removed pages with redirects, link updates, and one word in the Vale vocabulary. Reverting brings the old pages back.

Summary

Moves the React how-to guides from the Hilla section to Building Apps. This is the ninth step of dissolving the Hilla section, after #6611, #6616, #6618, #6620, #6621, #6622, #6624 and #6626. After it, only articles/hilla/index.adoc is left, for the last step.

Each how-to was rewritten for 25.4 and run end to end in a scratch 25.4.0-alpha5 application. This pull request targets main only, so it gets no target/v25.3 label.

What changed

• Work Offline (building-apps/react/work-offline), from the client caching guide:
  • cache the application with @PWA;
  • keep service results in local storage with a cacheable() helper, which falls back to them only when a call can't reach the server and passes EndpointErrors on;
  • show the connection status;
  • clear the data at logout.
• Upload and Download Files (building-apps/react/upload-download):
  • a Spring controller that receives files and sends them back;
  • the Spring Security rule it needs, because Vaadin's configuration denies other requests;
  • the Upload component posting to it with uploadFormat="multipart" and the CSRF header from Vaadin's _csrf meta tags;
  • the 1 MB default size limit of Spring Boot;
  • a download link with the download attribute.
• Test React Views (building-apps/react/test-views), rewritten from the Hilla testing guide:
  • Vitest browser mode with the Playwright provider and React Testing Library;
  • the signals transform in the test configuration;
  • mocking the generated clients with vi.mock();
  • generating the clients with mvn compile vaadin:generate for CI.
• Examples: compiled FileController, TaskService and TodoService, and views for each guide, replacing the old upload and download examples. The example controller is disabled in the docs application with the hidden @Profile("this-is-just-a-demo-class") line, because it stores uploads in memory.
• Removed pages, with redirects:
  • hilla/guides/client-caching → building-apps/react/work-offline
  • hilla/guides/uploads-downloads → building-apps/react/upload-download
  • hilla/guides/testing → building-apps/react/test-views
  • hilla/guides/data-grids → components/auto-grid
  • hilla/guides/from-java-to-react, hilla/faq and the now empty hilla/guides index → building-apps/react
  • The existing form-images, Lit FAQ, Lit client caching and Lit guides redirects point at the new pages.
• Links: Building Apps React index (new topics, no link to the Hilla guides), Testing, When to Use Vaadin, Add a Grid, and the MultipartFile row of Type Conversion.
• Vale: "Vitest" is added to the vocabulary.
• Corrections compared with the old pages:
  • The old upload approach cancelled the Upload request and sent the file to a browser-callable service. The Upload component frees a concurrent-upload slot only when its own request completes, so after three uploads new files stay "Queued". Reported as Upload: a prevented upload-request keeps its upload slot, so later files stay queued web-components#13387. The new guide uses a controller as the target.
  • The old caching helper returned cached data for every error, including access denied.
  • The old testing guide's Vitest configuration, getByLabelText() on a Vaadin text field, and vi.spyOn() on a generated client all fail, and its view example didn't compile.

Test summary

• npm run check-redirects passes.
• mvn spotless:apply and mvn compile pass. ESLint passes on the new examples.
• The new examples build with Vite 5.4.8, the version that the docs build uses.
• Work Offline, production build in the Playwright browser:
  • the view stores the tasks;
  • after the server stops, a reload comes from the service worker, shows the stored tasks, and shows "Connection lost";
  • with the cache cleared, it shows an empty list;
  • the logout snippet type-checks.
• Upload and Download Files, with Spring Security and a logged-in user:
  • five uploads in a row complete;
  • the download returns the file, and a non-ASCII name is encoded;
  • a 2 MB file fails with 413 by default and works with the limits from the page;
  • a request without the CSRF header gets 403;
  • clicking the download link doesn't navigate.
• Test React Views:
  • the three tests pass headless on a clean cache with Vitest 5.1.0, Playwright 1.65.0 and React Testing Library 16.3.3;
  • tsc -p src/test/frontend passes;
  • the failing alternatives (vi.spyOn(), getByLabelText(), no signals transform, no optimizeDeps.include) fail as the page says.
• Every cross reference in the new and changed lines resolves.
• Vale: no errors or warnings on the added and changed lines with the pull request configuration.
• Asciidoctor renders the new pages with all includes and tags resolved.
• I didn't run a full dspublisher build locally.

🤖 Generated with Claude Code

[vaadin-review-bot]

Reviewed the changes — left 1 comment.

	Finding
🧩	The upload and download snippets use a files signal that the page never shows.

[vaadin-review-bot]

🧩 The upload and download snippets use a files signal that the page never shows.

The upload tag of files-view.tsx starts at the <Upload> element. The download tag starts at the <ul>. Both use files.value, but the shown code never declares it:

const files = useSignal<StoredFile[]>([]);

The StoredFile type is also hidden. A reader who copies the two snippets gets files is not defined. Move the declaration and the type into a shown tag, or add a sentence that says the view keeps the uploaded files in a signal of { id, name } objects.

_{upload-download.adoc:57 · examples}

[github-actions]

Preview Deployment

This PR has been deployed for preview.

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

Changed pages

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

• building-apps/architecture/when-to-use-vaadin — modified, +1/-1 lines, 1 removal marker(s)
• building-apps/forms-data/add-grid — modified, +1/-1 lines, 1 removal marker(s)
• building-apps/react — modified, +4/-1 lines, 1 removal marker(s)
• building-apps/react/test-views — added, +208/-0 lines
• building-apps/react/upload-download — added, +94/-0 lines
• building-apps/react/work-offline — added, +88/-0 lines
• building-apps/testing — modified, +1/-1 lines, 1 removal marker(s)
• flow/react-views/browser-callable-services/type-conversion — modified, +1/-1 lines, 1 removal marker(s)

Other changed files

• articles/hilla/faq.adoc (deleted)
• articles/hilla/guides/client-caching.adoc (deleted)
• articles/hilla/guides/data-grids/index.adoc (deleted)
• articles/hilla/guides/from-java-to-react.adoc (deleted)
• articles/hilla/guides/index.adoc (deleted)
• articles/hilla/guides/testing.adoc (deleted)
• articles/hilla/guides/uploads-downloads.adoc (deleted)
• articles/hilla/guides/data-grids/data.sql (deleted)
• frontend/demo/fusion/forms/upload/download.tsx (deleted)
• frontend/demo/fusion/forms/upload/upload.tsx (deleted)
• src/main/java/com/vaadin/demo/SecurityConfig.java (modified)
• src/main/java/com/vaadin/demo/fusion/download/FileDownloadController.java (deleted)
• src/main/java/com/vaadin/demo/fusion/offline/TaskService.java (added)
• src/main/java/com/vaadin/demo/fusion/offline/package-info.java (added)
• src/main/java/com/vaadin/demo/fusion/upload/UploadService.java (deleted)

Built from b531f1d