feat: add API for switching between light and dark theme variants

Adds Page.setThemeVariant() and Page.getThemeVariant() methods
to enable runtime switching between theme variants without requiring
manual JavaScript execution. The theme variant is automatically synced
from the browser on page load if set in index.html.

The implementation supports both Lumo and Aura themes:
- Lumo: Sets/removes the 'theme' attribute on the HTML element
- Aura: Sets/removes the '--aura-color-scheme' CSS custom property

Key changes:
- Page API: setThemeVariant() and getThemeVariant() methods
- UIInternals: cache theme variant for quick access (returns "" not null)
- ExtendedClientDetails: include theme variant from browser
- FlowBootstrap.js: sync theme attribute and Aura color scheme on page load
- Comprehensive unit and integration tests

Fixes #15354

Author: Artur-

flow-client/src/main/frontend/Flow.ts

@@ -539,6 +539,24 @@ export class Flow {
       params['v-np'] = ($wnd as any).navigator.platform;
     }
 
+    /* Theme variant from HTML element - supports both Lumo and Aura */
+    let themeAttr = document.documentElement.getAttribute('theme');
+    if (!themeAttr) {
+      // If no theme attribute, check for Aura color scheme CSS property
+      const auraScheme = getComputedStyle(document.documentElement).getPropertyValue('--aura-color-scheme').trim();
+      themeAttr = auraScheme || '';
+    }
+    params['v-theme'] = themeAttr;
+    /* Theme name - detect which theme is in use */
+    const computedStyle = getComputedStyle(document.documentElement);
+    let themeName = '';
+    if (computedStyle.getPropertyValue('--vaadin-lumo-theme').trim()) {
+      themeName = 'lumo';
+    } else if (computedStyle.getPropertyValue('--vaadin-aura-theme').trim()) {
+      themeName = 'aura';
+    }
+    params['v-theme-name'] = themeName;
+
     /* Stringify each value (they are parsed on the server side) */
     const stringParams: Record<string, string> = {};
     Object.keys(params).forEach((key) => {

flow-server/src/main/java/com/vaadin/flow/component/page/ExtendedClientDetails.java

@@ -60,6 +60,8 @@ public class ExtendedClientDetails implements Serializable {
     private double devicePixelRatio = -1.0D;
     private String windowName;
     private String navigatorPlatform;
+    private String themeVariant;
+    private String themeName;
 
     /**
      * For internal use only. Updates all properties in the class according to
@@ -100,14 +102,18 @@ public class ExtendedClientDetails implements Serializable {
      *            a unique browser window name which persists on reload
      * @param navigatorPlatform
      *            navigation platform received from the browser
+     * @param themeVariant
+     *            the current theme variant
+     * @param themeName
+     *            the theme name (e.g., "lumo", "aura")
      */
     public ExtendedClientDetails(UI ui, String screenWidth, String screenHeight,
             String windowInnerWidth, String windowInnerHeight,
             String bodyClientWidth, String bodyClientHeight, String tzOffset,
             String rawTzOffset, String dstShift, String dstInEffect,
             String tzId, String curDate, String touchDevice,
             String devicePixelRatio, String windowName,
-            String navigatorPlatform) {
+            String navigatorPlatform, String themeVariant, String themeName) {
         this.ui = ui;
         if (screenWidth != null) {
             try {
@@ -184,6 +190,8 @@ public ExtendedClientDetails(UI ui, String screenWidth, String screenHeight,
 
         this.windowName = windowName;
         this.navigatorPlatform = navigatorPlatform;
+        this.themeVariant = themeVariant;
+        this.themeName = themeName;
     }
 
     /**
@@ -397,6 +405,35 @@ public boolean isIOS() {
                         && navigatorPlatform.startsWith("iPod"));
     }
 
+    /**
+     * Gets the theme variant.
+     *
+     * @return the theme variant, or empty string if not set
+     */
+    public String getThemeVariant() {
+        return themeVariant;
+    }
+
+    /**
+     * Gets the theme name.
+     *
+     * @return the theme name (e.g., "lumo", "aura"), or empty string if not
+     *         detected
+     */
+    public String getThemeName() {
+        return themeName;
+    }
+
+    /**
+     * Updates the theme variant. For internal use only.
+     *
+     * @param themeVariant
+     *            the new theme variant
+     */
+    void setThemeVariant(String themeVariant) {
+        this.themeVariant = themeVariant == null ? "" : themeVariant;
+    }
+
     /**
      * Creates an ExtendedClientDetails instance from browser details JSON
      * object. This is intended for internal use when browser details are
@@ -446,7 +483,9 @@ public static ExtendedClientDetails fromJson(UI ui, JsonNode json) {
                 getStringElseNull.apply("v-td"),
                 getStringElseNull.apply("v-pr"),
                 getStringElseNull.apply("v-wn"),
-                getStringElseNull.apply("v-np"));
+                getStringElseNull.apply("v-np"),
+                getStringElseNull.apply("v-theme"),
+                getStringElseNull.apply("v-theme-name"));
     }
 
     /**
@@ -474,4 +513,5 @@ public void refresh(Consumer<ExtendedClientDetails> callback) {
         };
         ui.getPage().executeJs(js).then(resultHandler, errorHandler);
     }
+
 }

flow-server/src/main/java/com/vaadin/flow/component/page/Page.java

@@ -84,6 +84,54 @@ public void setTitle(String title) {
         ui.getInternals().setTitle(title);
     }
 
+    /**
+     * Sets the theme variant for the page.
+     *
+     * @param variant
+     *            the theme variant to set (e.g., "dark", "light"), or
+     *            {@code null} or empty string to remove the theme variant
+     */
+    public void setThemeVariant(String variant) {
+        if (variant == null || variant.isEmpty()) {
+            executeJs(
+                    """
+                            document.documentElement.removeAttribute('theme');
+                            document.documentElement.style.removeProperty('--aura-color-scheme');
+                            """);
+            ui.getInternals().setThemeVariant(null);
+        } else {
+            executeJs(
+                    """
+                            document.documentElement.setAttribute('theme', $0);
+                            document.documentElement.style.setProperty('--aura-color-scheme', $0);
+                            """,
+                    variant);
+            ui.getInternals().setThemeVariant(variant);
+        }
+
+        // Update the cached value in ExtendedClientDetails
+        ExtendedClientDetails details = ui.getInternals()
+                .getExtendedClientDetails();
+        if (details != null) {
+            details.setThemeVariant(variant);
+        }
+    }
+
+    /**
+     * Gets the theme variant for the page.
+     * <p>
+     * Note that this method returns the server-side cached value and will not
+     * detect theme changes made directly via JavaScript or browser developer
+     * tools.
+     *
+     * @return the theme variant, or empty string if not set
+     */
+    public String getThemeVariant() {
+        ExtendedClientDetails details = ui.getInternals()
+                .getExtendedClientDetails();
+        return details != null ? details.getThemeVariant() : "";
+    }
+
     /**
      * Adds the given style sheet to the page and ensures that it is loaded
      * successfully.

flow-server/src/main/java/com/vaadin/flow/server/communication/IndexHtmlRequestHandler.java

@@ -177,7 +177,8 @@ public boolean synchronizedHandleRequest(VaadinSession session,
         }
 
         addDevBundleTheme(indexDocument, context);
-        applyThemeVariant(indexDocument, context);
+        applyThemeVariant(indexDocument, context,
+                indexHtmlResponse.getUI().orElse(null));
 
         if (config.isDevToolsEnabled()) {
             addDevTools(indexDocument, config, session, request);
@@ -254,11 +255,20 @@ private static void addDevBundleTheme(Document document,
     }
 
     private void applyThemeVariant(Document indexDocument,
-            VaadinContext context) {
+            VaadinContext context, UI ui) {
+        Element htmlElement = indexDocument.head().parent();
+
         ThemeUtils.getThemeAnnotation(context).ifPresent(theme -> {
             String variant = theme.variant();
             if (!variant.isEmpty()) {
-                indexDocument.head().parent().attr("theme", variant);
+                htmlElement.attr("theme", variant);
+                String style = htmlElement.attr("style");
+                String auraProperty = "--aura-color-scheme: " + variant + ";";
+                if (style != null && !style.isEmpty()) {
+                    htmlElement.attr("style", style + " " + auraProperty);
+                } else {
+                    htmlElement.attr("style", auraProperty);
+                }
             }
         });
     }

flow-server/src/test/java/com/vaadin/flow/component/page/ExtendedClientDetailsTest.java

@@ -161,14 +161,15 @@ private class ExtendBuilder {
         private String devicePixelRatio = "2.0";
         private String windowName = "ROOT-1234567-0.1234567";
         private String navigatorPlatform = "Linux i686";
+        private String themeVariant = null;
 
         public ExtendedClientDetails buildDetails() {
             return new ExtendedClientDetails(null, screenWidth, screenHeight,
                     windowInnerWidth, windowInnerHeight, bodyClientWidth,
                     bodyClientHeight, timezoneOffset, rawTimezoneOffset,
                     dstSavings, dstInEffect, timeZoneId, clientServerTimeDelta,
                     touchDevice, devicePixelRatio, windowName,
-                    navigatorPlatform);
+                    navigatorPlatform, themeVariant);
         }
 
         public ExtendBuilder setScreenWidth(String screenWidth) {

flow-server/src/test/java/com/vaadin/flow/component/page/PageTest.java

@@ -300,4 +300,125 @@ public PendingJavaScriptResult executeJs(String expression,
         MatcherAssert.assertThat(capture.get(), CoreMatchers
                 .startsWith("if ($1 == '_self') this.stopApplication();"));
     }
+
+    @Test
+    public void setThemeVariant_setsAttribute() {
+        AtomicReference<String> capturedExpression = new AtomicReference<>();
+        AtomicReference<Object> capturedParam = new AtomicReference<>();
+        MockUI mockUI = new MockUI();
+        Page page = new Page(mockUI) {
+            @Override
+            public PendingJavaScriptResult executeJs(String expression,
+                    Object... parameters) {
+                capturedExpression.set(expression);
+                if (parameters.length > 0) {
+                    capturedParam.set(parameters[0]);
+                }
+                return Mockito.mock(PendingJavaScriptResult.class);
+            }
+        };
+
+        page.setThemeVariant("dark");
+
+        String js = capturedExpression.get();
+        Assert.assertTrue(js.contains("setAttribute('theme', $0)"));
+        Assert.assertTrue(
+                js.contains("setProperty('--aura-color-scheme', $0)"));
+        Assert.assertEquals("dark", capturedParam.get());
+    }
+
+    @Test
+    public void setThemeVariant_null_removesAttribute() {
+        MockUI mockUI = new MockUI();
+
+        AtomicReference<String> capturedExpression = new AtomicReference<>();
+        Page page = new Page(mockUI) {
+            @Override
+            public PendingJavaScriptResult executeJs(String expression,
+                    Object... parameters) {
+                capturedExpression.set(expression);
+                return Mockito.mock(PendingJavaScriptResult.class);
+            }
+        };
+
+        page.setThemeVariant(null);
+
+        String js = capturedExpression.get();
+        Assert.assertTrue(js.contains("removeAttribute('theme')"));
+        Assert.assertTrue(js.contains("removeProperty('--aura-color-scheme')"));
+        Assert.assertEquals("", mockUI.getInternals().getThemeVariant());
+    }
+
+    @Test
+    public void setThemeVariant_emptyString_removesAttribute() {
+        MockUI mockUI = new MockUI();
+
+        AtomicReference<String> capturedExpression = new AtomicReference<>();
+        Page page = new Page(mockUI) {
+            @Override
+            public PendingJavaScriptResult executeJs(String expression,
+                    Object... parameters) {
+                capturedExpression.set(expression);
+                return Mockito.mock(PendingJavaScriptResult.class);
+            }
+        };
+
+        page.setThemeVariant("");
+
+        String js = capturedExpression.get();
+        Assert.assertTrue(js.contains("removeAttribute('theme')"));
+        Assert.assertTrue(js.contains("removeProperty('--aura-color-scheme')"));
+        Assert.assertEquals("", mockUI.getInternals().getThemeVariant());
+    }
+
+    @Test
+    public void getThemeVariant_returnsEmptyString_whenNotSet() {
+        Page page = new Page(new MockUI());
+        Assert.assertEquals("", page.getThemeVariant());
+    }
+
+    @Test
+    public void getThemeVariant_returnsCachedValue() {
+        MockUI mockUI = new MockUI();
+        // Set up ExtendedClientDetails with theme variant
+        ExtendedClientDetails details = new ExtendedClientDetails(mockUI, null,
+                null, null, null, null, null, null, null, null, null, null,
+                null, null, null, null, null, "dark", null);
+        mockUI.getInternals().setExtendedClientDetails(details);
+
+        Page page = new Page(mockUI);
+        Assert.assertEquals("dark", page.getThemeVariant());
+    }
+
+    @Test
+    public void setThemeVariant_updatesGetThemeVariant() {
+        MockUI mockUI = new MockUI();
+        // Set up ExtendedClientDetails
+        ExtendedClientDetails details = new ExtendedClientDetails(mockUI, null,
+                null, null, null, null, null, null, null, null, null, null,
+                null, null, null, null, null, null, null);
+        mockUI.getInternals().setExtendedClientDetails(details);
+
+        Page page = new Page(mockUI) {
+            @Override
+            public PendingJavaScriptResult executeJs(String expression,
+                    Object... parameters) {
+                return Mockito.mock(PendingJavaScriptResult.class);
+            }
+        };
+
+        Assert.assertEquals("", page.getThemeVariant());
+
+        page.setThemeVariant("dark");
+        Assert.assertEquals("dark", page.getThemeVariant());
+
+        page.setThemeVariant("light");
+        Assert.assertEquals("light", page.getThemeVariant());
+
+        page.setThemeVariant(null);
+        Assert.assertEquals("", page.getThemeVariant());
+
+        page.setThemeVariant("");
+        Assert.assertEquals("", page.getThemeVariant());
+    }
 }