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/FlowBootstrap.js

@@ -264,6 +264,15 @@ Please submit an issue to https://github.com/vaadin/flow-components/issues/new/c
         params['v-np'] = navigator.platform;
       }
 
+      /* Theme variant from HTML element - supports both Lumo and Aura */
+      var themeAttr = document.documentElement.getAttribute('theme');
+      if (!themeAttr) {
+        // If no theme attribute, check for Aura color scheme CSS property
+        var auraScheme = getComputedStyle(document.documentElement).getPropertyValue('--aura-color-scheme').trim();
+        themeAttr = auraScheme || '';
+      }
+      params['v-theme'] = themeAttr;
+
       /* Stringify each value (they are parsed on the server side) */
       Object.keys(params).forEach(function (key) {
         var value = params[key];

flow-server/src/main/java/com/vaadin/flow/component/internal/UIInternals.java

@@ -230,6 +230,8 @@ public List<Object> getParameters() {
 
     private ExtendedClientDetails extendedClientDetails = null;
 
+    private String themeVariant = "";
+
     private ArrayDeque<Component> modalComponentStack;
 
     /**
@@ -1366,6 +1368,25 @@ public void setExtendedClientDetails(ExtendedClientDetails details) {
         this.extendedClientDetails = details;
     }
 
+    /**
+     * Gets the theme variant that is currently set for the page.
+     *
+     * @return the theme variant, or empty string if not set
+     */
+    public String getThemeVariant() {
+        return themeVariant;
+    }
+
+    /**
+     * Sets the theme variant for the page.
+     *
+     * @param themeVariant
+     *            the theme variant to set, or {@literal null} to clear
+     */
+    public void setThemeVariant(String themeVariant) {
+        this.themeVariant = themeVariant == null ? "" : themeVariant;
+    }
+
     /**
      * Check if we have a modal component defined for the UI.
      *

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

@@ -49,6 +49,7 @@ public class ExtendedClientDetails implements Serializable {
     private double devicePixelRatio = -1.0D;
     private String windowName;
     private String navigatorPlatform;
+    private String themeVariant;
 
     /**
      * For internal use only. Updates all properties in the class according to
@@ -87,14 +88,16 @@ 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 from the HTML element
      */
     ExtendedClientDetails(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) {
         if (screenWidth != null) {
             try {
                 this.screenWidth = Integer.parseInt(screenWidth);
@@ -170,6 +173,7 @@ public class ExtendedClientDetails implements Serializable {
 
         this.windowName = windowName;
         this.navigatorPlatform = navigatorPlatform;
+        this.themeVariant = themeVariant;
     }
 
     /**
@@ -382,4 +386,13 @@ public boolean isIOS() {
                 || (navigatorPlatform != null
                         && navigatorPlatform.startsWith("iPod"));
     }
+
+    /**
+     * Gets the theme variant that is currently set on the HTML element.
+     *
+     * @return the theme variant, or empty string if not set
+     */
+    public String getThemeVariant() {
+        return themeVariant;
+    }
 }

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

@@ -88,6 +88,66 @@ public void setTitle(String title) {
         ui.getInternals().setTitle(title);
     }
 
+    /**
+     * Sets the theme variant for the page. This method supports both Lumo and
+     * Aura themes by setting the appropriate attributes and CSS properties.
+     * <p>
+     * For Lumo theme, this sets the {@code theme} attribute on the HTML
+     * document element. For Aura theme, this sets the
+     * {@code --aura-color-scheme} CSS custom property.
+     * <p>
+     * Example usage:
+     *
+     * <pre>
+     * // Switch to dark mode
+     * UI.getCurrent().getPage().setThemeVariant("dark");
+     *
+     * // Switch to light mode (or remove variant for Lumo)
+     * UI.getCurrent().getPage().setThemeVariant("");
+     * // or for explicit light mode in Aura
+     * UI.getCurrent().getPage().setThemeVariant("light");
+     * </pre>
+     *
+     * @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);
+        }
+    }
+
+    /**
+     * Gets the currently set theme variant for the page.
+     * <p>
+     * This returns the cached theme variant value that was either:
+     * <ul>
+     * <li>Set via {@link #setThemeVariant(String)}, or</li>
+     * <li>Retrieved from the browser on page load (if the theme attribute was
+     * set in index.html)</li>
+     * </ul>
+     * <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() {
+        return ui.getInternals().getThemeVariant();
+    }
+
     /**
      * Adds the given style sheet to the page and ensures that it is loaded
      * successfully.
@@ -533,24 +593,27 @@ private void handleExtendedClientDetailsResponse(JsonNode json) {
                 return null;
             }
         };
-        ui.getInternals()
-                .setExtendedClientDetails(new ExtendedClientDetails(
-                        getStringElseNull.apply("v-sw"),
-                        getStringElseNull.apply("v-sh"),
-                        getStringElseNull.apply("v-ww"),
-                        getStringElseNull.apply("v-wh"),
-                        getStringElseNull.apply("v-bw"),
-                        getStringElseNull.apply("v-bh"),
-                        getStringElseNull.apply("v-tzo"),
-                        getStringElseNull.apply("v-rtzo"),
-                        getStringElseNull.apply("v-dstd"),
-                        getStringElseNull.apply("v-dston"),
-                        getStringElseNull.apply("v-tzid"),
-                        getStringElseNull.apply("v-curdate"),
-                        getStringElseNull.apply("v-td"),
-                        getStringElseNull.apply("v-pr"),
-                        getStringElseNull.apply("v-wn"),
-                        getStringElseNull.apply("v-np")));
+        ExtendedClientDetails details = new ExtendedClientDetails(
+                getStringElseNull.apply("v-sw"),
+                getStringElseNull.apply("v-sh"),
+                getStringElseNull.apply("v-ww"),
+                getStringElseNull.apply("v-wh"),
+                getStringElseNull.apply("v-bw"),
+                getStringElseNull.apply("v-bh"),
+                getStringElseNull.apply("v-tzo"),
+                getStringElseNull.apply("v-rtzo"),
+                getStringElseNull.apply("v-dstd"),
+                getStringElseNull.apply("v-dston"),
+                getStringElseNull.apply("v-tzid"),
+                getStringElseNull.apply("v-curdate"),
+                getStringElseNull.apply("v-td"),
+                getStringElseNull.apply("v-pr"),
+                getStringElseNull.apply("v-wn"),
+                getStringElseNull.apply("v-np"),
+                getStringElseNull.apply("v-theme"));
+        ui.getInternals().setExtendedClientDetails(details);
+        // Cache the theme variant in UIInternals for quick access
+        ui.getInternals().setThemeVariant(details.getThemeVariant());
     }
 
     /**

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(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

@@ -366,4 +366,117 @@ 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());
+        Assert.assertEquals("dark", mockUI.getInternals().getThemeVariant());
+    }
+
+    @Test
+    public void setThemeVariant_null_removesAttribute() {
+        MockUI mockUI = new MockUI();
+        mockUI.getInternals().setThemeVariant("dark");
+
+        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();
+        mockUI.getInternals().setThemeVariant("dark");
+
+        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();
+        mockUI.getInternals().setThemeVariant("dark");
+
+        Page page = new Page(mockUI);
+        Assert.assertEquals("dark", page.getThemeVariant());
+    }
+
+    @Test
+    public void setThemeVariant_updatesCache() {
+        MockUI mockUI = new MockUI();
+        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());
+    }
 }