docs: add FLOW_COMPONENT_GUIDELINES and DESIGN_GUIDELINES#9143
Conversation
Document the implementation mechanics and design principles for Flow components so the conventions used across the existing modules are discoverable in one place, mirroring the equivalent guides in the web-components repository.
Flow APIs should use the positive, natural-language form for boolean properties (setEnabled, setVisible) even though the underlying web component uses the negative HTML form (disabled, hidden). The polarity flip happens at the element boundary inside the wrapper.
Property order independence, graceful behaviour before UI attachment, and no thrown errors for bad input (warnings instead).
Flow queues JS calls until connection rather than silently dropping them. Properties are stored server-side and synced on connect.
|
| - A component-specific extension or override. | ||
| - A specific interaction pattern not pinned down by the universal rule. | ||
|
|
||
| ### Every interactive element has an accessible name |
There was a problem hiding this comment.
This and a few other points below are covered in the web component design guidelines. IMO, we should not duplicate them here other than i18n part (should mention mapping web component i18n property to Java class). Things like "focus order" and RTL can be probably dropped.
|
|
||
| --- | ||
|
|
||
| ## Declarative (XML/Lumo) compatibility remains |
There was a problem hiding this comment.
note: what this XML/Lumo is about? This should be renamed.
|
|
||
| ## Declarative (XML/Lumo) compatibility remains | ||
|
|
||
| Flow components are sometimes consumed through Lit templates, Hilla, or server-side templating. The component's default state (zero-argument constructor + defaults) MUST produce something meaningful that renders correctly with no further calls. |
There was a problem hiding this comment.
thought: we should not mention Hilla, and generally reduce this section (it's not a common use case).
|
|
||
| **What this means in practice:** | ||
|
|
||
| - The web component declares `static experimental = true`; the Flow wrapper MUST be gated by the corresponding Vaadin feature flag (see `com.vaadin.experimental.FeatureFlags`). |
There was a problem hiding this comment.
note: web components use static get experimental() but this is kind of not relevant here?
|
|
||
| - The single-line-to-common-case principle keeps Flow application code readable: most buttons in a real application are created as `new Button("Save", e -> save())`, and that must not require boilerplate. | ||
| - Overloaded constructors make the component's intended uses discoverable through IDE autocompletion. | ||
| - Refusing fluent chains keeps Flow consistent with the rest of Vaadin Flow and Jakarta: everything is setter-based so that framework tooling (validation, binding, state restoration) sees the same shape. |
There was a problem hiding this comment.
note: "keeps Flow consistent with the rest of Vaadin Flow" sounds like a tautology, consider rephrasing.
|
|
||
| For implementation details, see [FLOW_COMPONENT_GUIDELINES.md](FLOW_COMPONENT_GUIDELINES.md). | ||
|
|
||
| For the design principles of the underlying web components, see `DESIGN_GUIDELINES.md` in the web-components repository; the Flow component's API must stay consistent with that design. |
There was a problem hiding this comment.
note: this should now mention guidelines folder instead of DESIGN_GUIDELINES.md file.
|
|
||
| - The web component is the source of truth for behaviour, DOM structure, theme variants, slots, shadow parts, and CSS custom properties. The Flow component must match the web component's semantics, not contradict them. | ||
| - If the web component exposes a property `disabled`, the Flow component's `setDisabled(boolean)` (usually via `HasEnabled`) must map to that property — not to something the Flow layer invents. | ||
| - If the web component exposes an event `opened-changed`, the Flow event listener must listen for that DOM event via `@DomEvent("opened-changed")` — not synthesise a separate Flow-only event. |
There was a problem hiding this comment.
note: this isn't quite true and in fact, "opened" property is not the best example - see #8230 for the change in Popover that removed @DomEvent for it. Consider using some other property name.
2 participants
Document the implementation mechanics and design principles for Flow components so the conventions used across the existing modules are discoverable in one place, mirroring the equivalent guides in the web-components repository.