Skip to content

docs: add Building Apps landing page intros, expand Strong Consistency, use Master-Detail Layout for form drawers - #6330

Merged
peholmst merged 1 commit into
mainfrom
claude/vaadin-docs-issue-6292-batch-b
Oct 9, 2026
Merged

peholmst merged 1 commit into
mainfrom
claude/vaadin-docs-issue-6292-batch-b

Conversation

@peholmst

@peholmst peholmst commented Oct 9, 2026

Copy link
Copy Markdown
Member

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 == Topics outline. 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:

  • Transactions, and how application services define them
  • Where Strong Consistency Ends: a monolith or self-contained system can use one local transaction, while microservices can't, which leads to Eventual Consistency
  • Concurrent Updates: lost updates, optimistic locking, and pessimistic locking
  • Stale Data in the User Interface: strong consistency doesn't refresh views that are already open; server push does

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() and LumoUtility classes. It now uses MasterDetailLayout:

  • The view extends MasterDetailLayout. It calls setDetail(drawer) when a proposal is selected and setDetail(null) when the selection is cleared.
  • The backdrop-click and Escape listeners clear the selection when the drawer is shown as an overlay.
  • It links to the Add a Master-Detail View guide.
  • It removes the LumoUtility styling (part of Building Apps: inconsistent Hilla/React terminology, Lumo/Aura token usage, and badges #6293).
  • It fixes setAriaLabeledBy, which doesn't exist, to setAriaLabelledBy.

The example uses only MasterDetailLayout API that is available from 25.0. setDetailPlaceholder() (25.2) is avoided, so no since badge is needed.

Checks

  • Compiled ProposalDrawer and ProposalView, extracted from the page, with javac -Xlint:deprecation against this repo's dependency classpath. The only stubs were Proposal, ProposalForm, and ProposalService. There were no errors or warnings.
  • All 52 added xrefs and anchors resolve.
  • Vale reports nothing on the changed lines.
  • No pages moved or removed, so no redirects are needed.

After this PR, the only // TODO left in Building Apps and Getting Started is the one in add-login.adoc. It's a placeholder inside the code sample for the reader to fill in, so it stays.

🤖 Generated with Claude Code

…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>
@peholmst peholmst added the target/v25.3 Automatically cherry-pick to the v25.3 branch label Oct 9, 2026
@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

Preview Deployment

This PR has been deployed for preview.

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

Changed pages

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

Built from d35934d

@peholmst
peholmst merged commit 3fa9bf0 into main Oct 9, 2026
11 checks passed
@peholmst
peholmst deleted the claude/vaadin-docs-issue-6292-batch-b branch October 9, 2026 10:38
peholmst added a commit that referenced this pull request Oct 9, 2026
…y, use Master-Detail Layout for form drawers (#6330) (CP: v25.3) (#6333)

Co-authored-by: Petter Holmström <petter@vaadin.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cherry-picked-v25.3 target/v25.3 Automatically cherry-pick to the v25.3 branch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Building Apps and Getting Started: inventory of stubs, empty landing pages, dead ends, and TODOs promising pages that don't exist

2 participants