Skip to content

Commit 3a906f7

Browse files
yuriy-fixyuriy-fix
committed
docs: add DS sections
1 parent 32690a9 commit 3a906f7

File tree

1 file changed

+335
-3
lines changed

1 file changed

+335
-3
lines changed

‎articles/upgrading/index.adoc‎

Lines changed: 335 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -184,9 +184,10 @@ Vaadin 25 simplifies the theme/styling system to bring it closer to normal/nativ
184184

185185
Below are the main highlights of the changes and more detailed instructions are described in link:https://github.com/vaadin/platform/issues/7453[Theming System Renewal].
186186

187-
188187
The special `frontend/themes` folder, and the `components` sub-folder for CSS shadow-DOM injection, is deprecated (but still supported).
189188

189+
Injecting CSS into Vaadin Components’ shadow DOM through the components subfolder in your theme folder is disabled by default. Shadow DOM styling is no longer recommended (as of V24), but if you still need to use it, it can be enabled with the feature flag `themeComponentStyles`.
190+
190191
The [classname]`@Theme` annotation is deprecated. Instead, [classname]`StyleSheet` annotation to be used for loading one or more stylesheets from public static resources locations (e.g. `META-INF/resources/`), whereas [classname]`CssImport` loads one or more stylesheets from the `src/main/frontend/` folder and use mechanisms native to HTML, CSS, and React (e.g. `@import url("morestyles.css")` in CSS).
191192

192193
`StyleSheet` annotation is now a recommended way to load Vaadin theme for the application — to be placed on the application class implementing [classname]`AppShellConfigurator`. Below are some examples of how to use it:
@@ -208,13 +209,344 @@ public class Application implements AppShellConfigurator {}
208209
// your custom styles go here ...
209210
210211
----
211-
212-
The [filename]`theme.json` configuration file is deprecated (but still supported).
212+
The [filename]`theme.json` configuration file is deprecated (but still supported, except the `lumoImports` property).
213213

214214
The `themeFor` parameter of the [classname]`@CssImport` annotation (for shadow-DOM injection) is deprecated (but still supported).
215215

216216
The special [filename]`document.css` file (for loading styles into the document root in embedded components) is removed as no longer necessary.
217217

218+
=== Themes
219+
220+
==== Lumo Theme
221+
The Lumo theme is no longer loaded by default, except if you’re using the [classname]`@Theme` annotation to load an application theme folder. If you’re not using [classname]`@Theme`, and instead load stylesheets with [classname]`@StyleSheet` or [classname]`@CssImport`, you need to add an import for Lumo in one of them:
222+
223+
[source,css]
224+
----
225+
@import "@vaadin/vaadin-lumo-styles/lumo.css";
226+
----
227+
228+
All Lumo styles, including badges, but excluding Lumo Utility Classes are included by default when the Lumo theme is loaded. To load the utility classes, add the following line to a stylesheet:
229+
230+
[source,css]
231+
----
232+
@import "@vaadin/vaadin-lumo-styles/utility.css";
233+
----
234+
235+
Vaadin 25 also supports Tailwind CSS utility classes.
236+
237+
NOTE: The way the Lumo theme is injected into Vaadin components has been refactored to not use the `registerStyles()` helper. This should not cause any breaking changes in applications; please report issues at link:https://github.com/vaadin/web-components/issues[vaadin/web-components] if you find otherwise.
238+
239+
==== Material Theme
240+
The Material theme is no longer supported in Vaadin 25. You can migrate your application to the Lumo or Aura theme or implement your own Material Design theme on top of the new component base styles.
241+
242+
==== Component Base Styles
243+
The un-themed base styles in Vaadin components have changed significantly in Vaadin 25. They are now much less bare-bones and actually provide a better starting point for custom themes. This does mean that custom themes built on top of the Vaadin 25 component base styles need to be heavily refactored. The components’ Styling pages provide lists of style properties (CSS custom properties) that make them easier to customize.
244+
245+
== Changes in Flow and Web Components
246+
247+
=== Themes and Styling
248+
249+
==== WebComponentExporter
250+
The [classname]`WebComponentExporter` feature in Flow allows you to export Flow components as Web Components for embedding into non-Vaadin UIs. In Vaadin 25, stylesheets loaded into exported components using the [classname]`@CssImport` annotation only load those styles into the exported component’s shadow DOM, not the surrounding page as before. To load the same styles into the surrounding page, import the stylesheet to it separately.
251+
252+
==== Overlays
253+
Component overlays (like Dialog or the ComboBox dropdown) are no longer rendered outside of the component itself. This causes the following breaking changes to overlay styling:
254+
255+
* The `overlayClass` property and the [methodname]`setOverlayClassName` method in Flow are gone. Apply a normal classname to the component instead.
256+
* The `vaadin-xyz-overlay` (such as `vaadin-dialog-overlay`) elements have been removed (as they are now unnecessary). Refactor any CSS targeting these elements to target the component itself instead (e.g. `vaadin-dialog` instead of `vaadin-dialog-overlay`). Other CSS selectors are unaffected by this change.
257+
258+
You’ll find the appropriate selector in the component’s Styling page.
259+
260+
==== React Components
261+
The Lumo CSS files have been removed from the `@vaadin/react-components` package. As mentioned above, the Lumo theme should be imported from `@vaadin/vaadin-lumo-styles` instead.
262+
263+
.Before
264+
[source,typescript]
265+
----
266+
/* If imported through a CSS file */
267+
@import '@vaadin/react-components/css/Lumo.css';
268+
269+
/* If imported through Typescript */
270+
import '@vaadin/react-components/css/Lumo.css';
271+
----
272+
273+
.After
274+
[source,typescript]
275+
----
276+
/* If imported through a CSS file */
277+
@import '@vaadin/vaadin-lumo-styles/lumo.css';
278+
279+
/* If imported through Typescript */
280+
import '@vaadin/vaadin-lumo-styles/lumo.css';
281+
----
282+
283+
One exception is the `@vaadin/react-components/css/lumo/Utility.module.css` CSS module, which has been preserved for backward compatibility as the Lumo package does not expose utilities as a CSS module.
284+
285+
=== Components
286+
287+
==== App Layout
288+
The `bottom` attribute was removed and can no longer be used to target the bottom navbar. Instead, use the selector `::part(navbar-bottom)` to target it with CSS.
289+
290+
==== Cookie Consent
291+
The Cookie Consent component has been removed. Vaadin does not provide any replacement, but several third party options exist, such as link:https://github.com/orestbida/cookieconsent[orestbida/cookieconsent].
292+
293+
==== Confirm Dialog
294+
The Flow [classname]`ConfirmDialog` now only implements [classname]`HasComponents` instead of [classname]`HasOrderedComponents`. The following methods are not available anymore: [methodname]`replace`, [methodname]`indexOf`, [methodname]`getComponentCount`, [methodname]`getComponentAt`, [methodname]`getChildren`.
295+
296+
Methods that allowed passing an [classname]`Element` instance have been removed. Use the corresponding alternatives that allow passing a [classname]`Component` instance instead.
297+
298+
==== Context Menu
299+
The [methodname]`add` method has been removed from the Flow [classname]`ContextMenu`. Instead, use [methodname]`addItem` to add menu items, or [methodname]`addComponent` to add generic components without wrapping them into a menu item.
300+
301+
==== Popover
302+
The Lit/React component’s `contentWidth` and `contentHeight` properties have been replaced by `width` and `height`.
303+
304+
==== CRUD
305+
The “New Item” button in the CRUD component no longer uses the primary style variant by default. To get the old default back:
306+
307+
[.example]
308+
[source,java]
309+
----
310+
crud.getNewButton().addThemeVariants(ButtonVariant.LUMO_PRIMARY);
311+
----
312+
313+
==== Grid & Tree Grid
314+
Tree Grid’s client-side approach to data loading has been refactored. Instead of requesting each hierarchy level separately, it now sends a single request to the server and receives all visible data in a flat list. This results in two important changes:
315+
316+
* [propertyname]`pageSize` now applies to the entire flattened hierarchy rather than each level individually as before
317+
* [propertyname]`expandedItems` are no longer exposed to the client side as a full array; only the depth of visible items is provided
318+
319+
The [classname]`TreeGridElement#isLoadingExpandedRows` TestBench API has been removed. You no longer need to wait for expanded rows specifically since they are loaded in the same request with other rows.
320+
321+
The [classname]`TreeGridElement#getNumberOfExpandedRows` TestBench API has been removed. Use unit tests instead to verify that exact items are expanded.
322+
323+
.Before (integration test)
324+
[source,java]
325+
----
326+
private TreeGridElement treeGridElement;
327+
328+
@Test
329+
public void shouldHaveSomeRowsExpanded() {
330+
Assert.assertEquals(2, treeGridElement.getNumberOfExpandedItems());
331+
}
332+
----
333+
334+
.After (unit test)
335+
[source,java]
336+
----
337+
private TreeGrid<String> treeGrid;
338+
339+
@Test
340+
public void shouldHaveSomeRowsExpanded() {
341+
Assert.assertTrue(treeGrid.isExpanded("Item 0"));
342+
Assert.assertTrue(treeGrid.isExpanded("Item 0-1"));
343+
}
344+
----
345+
346+
The section below is relevant if your code extends Grid or TreeGrid, or uses low-level APIs like [classname]`HierarchicalDataCommunicator`.
347+
348+
===== Low-level API changes
349+
The [classname]`GridArrayUpdater.UpdateQueueData` class has been removed, along with related APIs:
350+
351+
* The [methodname]`setUpdateQueueData` method in [classname]`GridArrayUpdater` has been removed
352+
* The [methodname]`getUpdateQueueData` method in [classname]`GridArrayUpdater` has been removed
353+
* Parameters that included [classname]`UpdateQueueData` in their type have been removed from all constructors and methods
354+
355+
.Before
356+
[source,java]
357+
----
358+
protected <U extends GridArrayUpdater, B extends DataCommunicatorBuilder<T, U>> Grid(
359+
Class<T> beanType,
360+
SerializableBiFunction<UpdateQueueData, Integer, UpdateQueue> updateQueueBuilder,
361+
B dataCommunicatorBuilder)
362+
363+
...
364+
365+
protected GridArrayUpdater createDefaultArrayUpdater(
366+
SerializableBiFunction<UpdateQueueData, Integer, UpdateQueue> updateQueueFactory)
367+
----
368+
369+
.After
370+
[source,java]
371+
----
372+
protected <U extends GridArrayUpdater, B extends DataCommunicatorBuilder<T, U>> Grid(
373+
Class<T> beanType,
374+
B dataCommunicatorBuilder)
375+
376+
...
377+
378+
protected GridArrayUpdater createDefaultArrayUpdater()
379+
----
380+
381+
The [classname]`TreeGridArrayUpdater` interface has been removed. The [classname]`GridArrayUpdater` interface should be used instead.
382+
383+
==== Charts
384+
The [methodname]`setWidthAdjust` / [methodname]`getWidthAdjust` methods of the [classname]`Title` class have been removed because it was removed from the underlying HighCharts library.
385+
386+
The [classname]`DrillUpButton` class has been removed from the codebase and all of its related API, e.g., [methodname]`setDrillUpButton` / [methodname]`getDrillUpButton` from the [classname]`Drilldown` class. Use Breadcrumbs instead. Likewise, the [methodname]`setDrillUpText` / [methodname]`getDrillUpText` has been removed from the [classname]`Lang` class.
387+
388+
All methods that accept [classname]`Date` as parameter that were previously marked as deprecated have been removed.
389+
390+
Chart configurations are now serialized using Jackson 3. The [methodname]`ChartSerialization.setObjectMapperInstance` method that can be used to customize serialization behavior now expects a [classname]`tools.jackson.databind.ObjectWriter` instance.
391+
392+
==== Date Picker and Date Time Picker
393+
The following changes have been made to the internal DOM structure of the Date Picker overlay, which may affect custom styling:
394+
395+
* The `vaadin-date-picker-overlay-content` element is now a CSS grid layout instead of a flexbox.
396+
* The `overlay-header` part has been removed.
397+
398+
==== Date Time Picker
399+
In the Flow [classname]`DateTimePicker` component, validation is no longer triggered on blur if the value remains unchanged after user interaction, making this behavior consistent with the rest of the field components, which already received a similar update in V24.
400+
401+
Incomplete input, where only a date or only a time is entered, is now treated as invalid. The corresponding error message can be configured via [classname]`DateTimePickerI18n`:
402+
403+
[.example]
404+
[source,java]
405+
----
406+
dateTimePicker.setI18n(new DateTimePickerI18n()
407+
.setIncompleteInputErrorMessage("Please enter both date and time"));
408+
----
409+
410+
==== Time Picker
411+
The Time Picker no longer uses `vaadin-time-picker-combo-box` internally. This may affect custom shadow DOM styling of the component.
412+
413+
The [classname]`TimePickerOverlayElement` TestBench element has been removed as the component now uses the native HTML popover mechanism for its dropdown. The [methodname]`getItem` and [methodname]`getLastItem` methods are now available on [classname]`TimePickerElement` itself.
414+
415+
==== Details
416+
The [methodname]`setContent` and [methodname]`addContent` methods have been removed from the Flow [classname]`Details` component. Use regular methods from [classname]`HasComponents` such as [methodname]`add`, [methodname]`remove`, [methodname]`removeAll` instead.
417+
418+
==== Dialog and Confirm Dialog
419+
[classname]`Dialog` and [classname]`ConfirmDialog` do not show a closing animation anymore when just removing the component from the UI / DOM. Instead, the dialog should be closed and the `closed` event needs to be used to wait for the closing animation to finish before removing the component.
420+
421+
For Flow this is relevant when manually adding / removing the dialog from the UI. The event is not needed when just calling [methodname]`dialog.open()` without adding the dialog to the UI.
422+
423+
.Before
424+
[source,java]
425+
----
426+
var dialog = new Dialog();
427+
add(dialog);
428+
dialog.open();
429+
430+
// When dialog is not needed anymore
431+
remove(dialog);
432+
----
433+
434+
.After
435+
[source,java]
436+
----
437+
var dialog = new Dialog();
438+
dialog.addClosedListener(e -> remove(dialog));
439+
add(dialog);
440+
dialog.open();
441+
442+
// When dialog is not needed anymore
443+
dialog.close();
444+
----
445+
446+
For Hilla / React this is relevant when rendering dialogs conditionally.
447+
448+
.Before
449+
[source,typescript]
450+
----
451+
const opened = useSignal(true);
452+
453+
{ opened ? <Dialog opened={true}/> : null }
454+
455+
// When dialog is not needed anymore
456+
opened.value = false;
457+
----
458+
459+
.After
460+
[source,typescript]
461+
----
462+
const ref = useRef<DialogElement>(null);
463+
const opened = useSignal(true);
464+
465+
{
466+
opened
467+
? <Dialog opened={true} ref={ref} onClosed={() => opened.value = false}/>
468+
: null
469+
}
470+
471+
// When dialog is not needed anymore
472+
ref.current?.close();
473+
----
474+
475+
==== Form Layout
476+
The following custom CSS properties have been removed from `vaadin-form-item`:
477+
478+
* `--vaadin-form-item-label-width`
479+
* `--vaadin-form-item-label-spacing`
480+
* `--vaadin-form-item-row-spacing`
481+
482+
Use the following CSS properties on `vaadin-form-layout` instead:
483+
484+
* `--vaadin-form-layout-label-width`
485+
* `--vaadin-form-layout-label-spacing`
486+
* `--vaadin-form-layout-row-spacing`
487+
488+
==== Map
489+
The Map component’s `borderless` / `BORDERLESS` style variant has been renamed `no-border` / `NO_BORDER` for consistency with other components.
490+
491+
==== Menu Bar
492+
The TestBench API `MenuBarElement.OVERLAY_TAG` has been removed. To get a reference to a submenu, instead use [methodname]`MenuBarButtonElement.openSubMenu` which returns a reference.
493+
494+
==== Message Input
495+
The send button no longer uses the Primary style variant by default. To revert this change you can style the button with CSS:
496+
497+
[.example]
498+
[source,css]
499+
----
500+
vaadin-message-input > vaadin-message-input-button {
501+
background-color: var(--lumo-primary-color);
502+
color: var(--lumo-primary-contrast-color);
503+
}
504+
----
505+
506+
Also, the send button now is a `vaadin-message-input-button` instead of `vaadin-button`.
507+
508+
==== Multi-Select Combo Box
509+
The Multi-Select Combo Box no longer uses `vaadin-multi-select-combo-box-internal` internally. This may affect custom shadow DOM styling of the component.
510+
511+
==== Rich Text Editor
512+
The `on` attribute was removed and can no longer be used to target toggled-on buttons. Instead, use the selector `::part(toolbar-button-pressed)` to target them with CSS.
513+
514+
==== Split Layout
515+
The Split Layout component no longer sets `overflow:auto` on its two child elements. The link:https://vaadin.com/docs/latest/components/scroller[Scroller] component is recommended to make them scrollable on overflow. Alternatively, you can apply it manually with CSS:
516+
517+
[.example]
518+
[source,css]
519+
----
520+
vaadin-split-layout > * {
521+
overflow: auto;
522+
}
523+
----
524+
525+
The `SplitterDragendEvent` and `addSplitterDragendListener` have been renamed to `SplitterDragEndEvent` and `addSplitterDragEndListener`, respectively.
526+
527+
==== Tabs / Tab Sheet
528+
The [classname]`TabsVariant.LUMO_ICON_ON_TOP` and [classname]`TabSheetVariant.LUMO_ICON_ON_TOP` theme variants have been removed. Apply the [classname]`TabVariant.LUMO_ICON_ON_TOP` to individual tabs instead.
529+
530+
==== Text Field
531+
The [classname]`HasPrefixAndSuffix` interface has been removed from the Flow [classname]`TextField` and related components. The components now implement [classname]`HasPrefix` and [classname]`HasSuffix` instead.
532+
533+
==== Upload
534+
The `upload-file` elements representing files in the list now use CSS grid layout instead of flexbox. This may affect custom styling of the element.
535+
536+
The `row` and `info` parts have been removed.
537+
538+
==== Validation
539+
Flow components using validation do not implement [classname]`HasClientValidation` anymore, as such the [methodname]`addClientValidatedEventListener` method has been removed. Consider using [classname]`ValidationStatusChangeEvent` to get notified when users enter input that can not be parsed.
540+
541+
=== Optional Changes
542+
543+
These changes are optional, as old approaches still work (with the exceptions listed in the Breaking Changes section), but recommended to get your app to the new best practices in Vaadin 25, and to avoid breaking changes in later major versions.
544+
545+
* Refactor component styles from shadow DOM styles to normal css (this was the recommended approach already in V24)
546+
* Single [classname]`@CssImport` of master stylesheet instead of [classname]`@Theme` or multiple [classname]`@CssImport`-s
547+
* Load additional stylesheets through master stylesheet with `@import`
548+
* Move stylesheets from `frontend/themes/<mytheme>` to `frontend`
549+
218550
== Security Configuration Changes
219551

220552
The deprecated [classname]`VaadinWebSecurity` class has been removed from Vaadin 25. Use instead the [classname]`VaadinSecurityConfigurer` base class for your security configuration. Below is an example of this:

0 commit comments

Comments
 (0)