Repository navigation
docs: add Building Apps landing page intros, expand Strong Consistency, use Master-Detail Layout for form drawers - #6330
Merged
Conversation
…y, use Master-Detail Layout for form drawers Finishes the remaining items in #6292: - Give the seven empty section landing pages (UI Basics, Views & Navigation, Forms & Data, Business Logic, Security, Integration, and Components) an introduction and a reading order. Fix their front matter: Forms & Data no longer promises Hilla, and Integration no longer promises integration with other systems in general. - Replace the Strong Consistency stub with a page on transactions, where strong consistency ends, concurrent updates, and stale data in views. - Rewrite the drawer section of Dialogs & Drawers around Master-Detail Layout, replacing hand-built visibility toggling and LumoUtility styling. This also fixes a call to setAriaLabeledBy, which doesn't exist. - Remove the Hilla promise from the Add a Form meta-description. Closes #6292 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
Preview DeploymentThis PR has been deployed for preview. URL: https://docs-preview-pr-6330.fly.dev Changed pagesAdded content is highlighted in green; removed content is marked in red on each page.
Built from d35934d |
peholmst
added a commit
that referenced
this pull request
Oct 9, 2026
…lding Apps and Getting Started (#6337) Closes #6293. Four bullets in the issue were already fixed on `main` before this PR: the forms meta-descriptions (#6330), `package-component.adoc` (now recommends `--vaadin-*`), `show-notification.adoc` (now `ButtonVariant.TERTIARY`), and `dialogs-and-drawers.adoc` (no `LumoUtility` left). ## Hilla vs React views - **Convention:** the Building Apps landing page now says the guides use Flow views unless they say otherwise. Instead of badging every Flow-only page, I removed the redundant Flow badges from `callbacks.adoc`, `futures.adoc`, and the AI quick start. The background-jobs overview says which options also work with React views. - `architecture/layers.adoc`, `server-push/index.adoc`, and the two consistency pages talk about Flow views and React views instead of Flow and Hilla. The diagram already said "Flow UI" and "React UI"; only its alt text changed. - `interaction/reactive.adoc`: - The Hilla-only constraints are now phrased for React views. The Flux-only warning still holds: Hilla's `TransferTypesPlugin` maps `Flux` but not `Mono`. - The deprecated `com.vaadin.hilla.Nullable` import is now `org.jspecify.annotations.Nullable`. - I removed the note saying sealed interfaces aren't supported. It's stale: Hilla supports polymorphic types through `@JsonTypeInfo` and `@JsonSubTypes` (its subtypes generator plugin). - Add a Form and Add a Grid point React readers to the Hilla forms and data grid guides. - Getting Started: the templates and Playground pages say React instead of Hilla. The IDE page explains that TypeScript support only matters if you add React views. ## Lumo vs Aura vs `--vaadin-*` Convention: examples use the theme-neutral `--vaadin-*` base style properties where they exist. Those don't cover accent colors, semantic colors (success/warning/error), or font sizes. For those, the examples use Aura, the default theme, and name the Lumo equivalent in one sentence. - `ui-basics/add-styling.adoc`: all examples converted. The intro no longer claims the examples are Lumo but work the same with Aura. - `components/build-component.adoc`: `--vaadin-gap-xs` and Aura status colors, with a note on the Lumo equivalents. - `components/style-component.adoc`: Aura is listed before Lumo and gets an example table like Lumo's. - `forms-data/add-form/validation.adoc`: `LumoUtility.TextColor.ERROR`, which has no effect under Aura, is replaced with a CSS class and a stylesheet rule. - `responsive.adoc`, `css-grid.adoc`, `create-custom-field`, and the PDF page already flag their Lumo assumption, so I left them as they are. ## Smaller drift - **Dev terms:** the five IDE run pages said "Hot deploy of the frontend files is enabled automatically". That's wrong: hot deploy is an opt-in mode. `run/index.adoc` now defines live reload, hotswap, and hot deploy once, matching the Flow reference, and recommends hotswap. - **Naming:** - "Dev Environment" is now "Development Environment". - The quick start introduces Vaadin Copilot as unrelated to GitHub Copilot at first mention. - The View Builder page now spells "Vaadin Start Playground" with a capital P. - **Xrefs:** 15 pages that mixed `<</...>>` and `<<{articles}/...>>` now use `{articles}` throughout. Five xrefs lost their `.adoc` suffix. - **Order and location:** `replace-h2.adoc` moved to `persistence/replace-h2.adoc` (order 7, after Add Flyway), with a redirect. Persistence moved from order 10 to 20, so it no longer clashes with Add a Grid. - **Front matter:** added descriptions to `react/add-view.adoc` and `react/call-services.adoc`, and a page title and meta-description to `server-push/reactive.adoc`. Fixed a "use use" typo in `threads.adoc`. ## Verification - Ran the docs locally and checked every internal link and anchor on all 46 changed pages: all resolve. The old Replace H2 URL returns a 301. - `npm run check-redirects` passes. - Vale reports nothing new; the remaining warnings were already in the text before this PR. ## Not in this PR The Getting Started tutorial calls `LumoUtility.BoxShadow.MEDIUM` in its drawer listings. That only works with Lumo and `Lumo.UTILITY_STYLESHEET` loaded. The quick start uses the same skeleton and its screenshots show Aura, so the shadow is probably a no-op today. Confirming that needs the real skeleton, so it's left for a separate change. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #6292. This is the second batch. The first one was #6320, and #6321 added the error-handling guide.
Section landing pages
Seven Building Apps section landing pages had front matter but no content: UI Basics, Views & Navigation, Forms & Data, Business Logic, Security, Integration, and Components. Each now has a short introduction, where to start, links to related sections, and a
== Topicsoutline. This follows the pattern of the Testing and React Views pages.Front matter fixes on these pages:
Strong Consistency
Replaced the stub and its TODO ("monoliths and self-contained systems") with four sections:
Dialogs & Drawers
The drawer section had a TODO saying "Write about the new master-detail layout" and built the drawer by hand. It used
setVisible()andLumoUtilityclasses. It now usesMasterDetailLayout:MasterDetailLayout. It callssetDetail(drawer)when a proposal is selected andsetDetail(null)when the selection is cleared.LumoUtilitystyling (part of Building Apps: inconsistent Hilla/React terminology, Lumo/Aura token usage, and badges #6293).setAriaLabeledBy, which doesn't exist, tosetAriaLabelledBy.The example uses only
MasterDetailLayoutAPI that is available from 25.0.setDetailPlaceholder()(25.2) is avoided, so no since badge is needed.Checks
ProposalDrawerandProposalView, extracted from the page, withjavac -Xlint:deprecationagainst this repo's dependency classpath. The only stubs wereProposal,ProposalForm, andProposalService. There were no errors or warnings.After this PR, the only
// TODOleft in Building Apps and Getting Started is the one inadd-login.adoc. It's a placeholder inside the code sample for the reader to fill in, so it stays.🤖 Generated with Claude Code