feat: Add pageVisibilitySignal() to Page for tracking browser tab visibility (#23614)

Add a read-only signal-based API on Page that tracks whether the browser
tab is visible and focused, visible but not focused, or hidden. Uses the
browser Page Visibility API combined with focus/blur events, with a
Firefox workaround for deferred visibilitychange. Client-side logic
lives in page-visibility.js loaded via @jsmodule on UI.

---------

Co-authored-by: Marco Collovati <marco@vaadin.com>

Author: Artur-

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

@@ -5,6 +5,7 @@ import {
   type ConnectionStateStore
 } from '@vaadin/common-frontend';
 import './Geolocation';
+import { currentVisibility } from './PageVisibility';
 
 export interface FlowConfig {
   imports?: () => Promise<any>;
@@ -541,6 +542,9 @@ export class Flow {
     const colorScheme = getComputedStyle(document.documentElement).colorScheme.trim();
     // "normal" is the default value and means no color scheme is set
     params['v-cs'] = colorScheme && colorScheme !== 'normal' ? colorScheme : '';
+    /* Page visibility — initial state of document.hidden / document.hasFocus() */
+    params['v-pv'] = currentVisibility();
+
     /* Theme name - detect which theme is in use */
     const computedStyle = getComputedStyle(document.documentElement);
     let themeName = '';

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

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+type VaadinPageVisibility = 'VISIBLE' | 'VISIBLE_NOT_FOCUSED' | 'HIDDEN';
+
+// Firefox defers the visibilitychange event while the window is blurred, so
+// a blur handler needs to wait long enough for that delivery to land before
+// concluding the state is really "visible but not focused".
+const FIREFOX_BLUR_SETTLE_MS = 500;
+const DEFAULT_BLUR_SETTLE_MS = 10;
+
+/**
+ * Returns the current visibility state synchronously. Used by the bootstrap
+ * path to seed the server-side signal without waiting for a DOM event.
+ */
+export function currentVisibility(): VaadinPageVisibility {
+  if (document.hidden) {
+    return 'HIDDEN';
+  }
+  return document.hasFocus() ? 'VISIBLE' : 'VISIBLE_NOT_FOCUSED';
+}
+
+function isFirefox(): boolean {
+  // Firefox is the only supported browser that reorders visibilitychange
+  // relative to blur; UA sniffing is acceptable here because the alternative
+  // is waiting the longer interval on every browser.
+  return navigator.userAgent.indexOf('Firefox') > -1;
+}
+
+let blurTimer: ReturnType<typeof setTimeout> | undefined;
+
+// Dispatch on document.body so the server-side Page facade (listening on
+// the UI element, which is body) can update its signal.
+function dispatch(state: VaadinPageVisibility): void {
+  document.body.dispatchEvent(new CustomEvent('vaadin-page-visibility-change', { detail: state }));
+}
+
+function clearBlurTimer(): void {
+  if (blurTimer !== undefined) {
+    clearTimeout(blurTimer);
+    blurTimer = undefined;
+  }
+}
+
+document.addEventListener('visibilitychange', () => {
+  clearBlurTimer();
+  dispatch(document.hidden ? 'HIDDEN' : 'VISIBLE');
+});
+
+window.addEventListener('blur', () => {
+  clearBlurTimer();
+  const delay = isFirefox() ? FIREFOX_BLUR_SETTLE_MS : DEFAULT_BLUR_SETTLE_MS;
+  blurTimer = setTimeout(() => {
+    blurTimer = undefined;
+    if (!document.hidden) {
+      dispatch('VISIBLE_NOT_FOCUSED');
+    }
+  }, delay);
+});
+
+window.addEventListener('focus', () => {
+  clearBlurTimer();
+  if (!document.hidden) {
+    dispatch('VISIBLE');
+  }
+});

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

@@ -498,6 +498,7 @@ public static ExtendedClientDetails updateFromJson(UI ui, JsonNode json) {
                 getStringElseNull.apply("v-cs"),
                 getStringElseNull.apply("v-tn"));
         ui.getInternals().setExtendedClientDetails(details);
+        ui.getPage().setPageVisibility(getStringElseNull.apply("v-pv"));
         String ga = getStringElseNull.apply("v-ga");
         if (ga != null) {
             try {

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

@@ -24,6 +24,9 @@
 import java.util.Objects;
 import java.util.UUID;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 import com.vaadin.flow.component.Direction;
 import com.vaadin.flow.component.UI;
 import com.vaadin.flow.component.dependency.JavaScript;
@@ -52,11 +55,17 @@
  */
 public class Page implements Serializable {
 
+    private static final Logger LOGGER = LoggerFactory.getLogger(Page.class);
+
     private final UI ui;
     private final History history;
     private DomListenerRegistration resizeReceiver;
     private ArrayList<BrowserWindowResizeListener> resizeListeners;
     private ValueSignal<WindowSize> windowSizeSignal;
+    private final ValueSignal<PageVisibility> pageVisibilitySignal = new ValueSignal<>(
+            PageVisibility.UNKNOWN);
+    private final Signal<PageVisibility> pageVisibilityReadOnly = pageVisibilitySignal
+            .asReadonly();
 
     /**
      * Creates a page instance for the given UI.
@@ -67,6 +76,10 @@ public class Page implements Serializable {
     public Page(UI ui) {
         this.ui = ui;
         history = new History(ui);
+        ui.getElement()
+                .addEventListener("vaadin-page-visibility-change",
+                        e -> setPageVisibility(e.getEventDetail(String.class)))
+                .addEventDetail().debounce(100).allowInert();
     }
 
     /**
@@ -477,6 +490,67 @@ private void ensureResizeListener() {
         }
     }
 
+    /**
+     * Returns a read-only signal that tracks the browser tab's visibility and
+     * focus state.
+     * <p>
+     * The signal distinguishes between {@link PageVisibility#VISIBLE VISIBLE}
+     * (tab shown and focused), {@link PageVisibility#VISIBLE_NOT_FOCUSED
+     * VISIBLE_NOT_FOCUSED} (tab shown but behind another window or another
+     * application has focus), {@link PageVisibility#HIDDEN HIDDEN} (tab in
+     * background, minimized, or on a different virtual desktop), and
+     * {@link PageVisibility#UNKNOWN UNKNOWN} (the initial value, replaced with
+     * a real one before any user code observes the signal).
+     * <p>
+     * The signal value is seeded from the initial client bootstrap, so user
+     * code always sees a real value. Subscribe with
+     * {@code Signal.effect(owner, ...)} to react to changes; call
+     * {@code pageVisibilitySignal().peek()} for a snapshot outside a reactive
+     * context, and {@code .get()} inside one.
+     * <p>
+     * <b>Reliability caveats.</b> The value is best-effort:
+     * <ul>
+     * <li>Firefox defers the {@code visibilitychange} event while the window is
+     * blurred, so transitions from {@link PageVisibility#VISIBLE VISIBLE} to
+     * {@link PageVisibility#HIDDEN HIDDEN} may take up to half a second longer
+     * than on Chromium or Safari.</li>
+     * <li>The {@link PageVisibility#VISIBLE_NOT_FOCUSED VISIBLE_NOT_FOCUSED}
+     * distinction relies on {@code document.hasFocus()}, which is accurate in
+     * all supported browsers but depends on the OS reporting focus changes
+     * promptly — some window-manager configurations can delay it briefly.</li>
+     * <li>Rapid focus/blur bursts are intentionally coalesced
+     * ({@code debounce(100)}) so the signal settles once the sequence ends
+     * instead of firing on each intermediate state.</li>
+     * </ul>
+     *
+     * @return the read-only visibility signal
+     */
+    public Signal<PageVisibility> pageVisibilitySignal() {
+        return pageVisibilityReadOnly;
+    }
+
+    /**
+     * Sets the page visibility from a raw client-side value (e.g. from the
+     * bootstrap parameters or from a {@code vaadin-page-visibility-change} DOM
+     * event). {@code null} and unknown values are ignored — the latter is
+     * logged at debug level so a forward-compatible client value does not
+     * silently disappear.
+     *
+     * @param value
+     *            the raw value, or {@code null}
+     */
+    void setPageVisibility(String value) {
+        if (value == null) {
+            return;
+        }
+        try {
+            pageVisibilitySignal.set(PageVisibility.valueOf(value));
+        } catch (IllegalArgumentException e) {
+            LOGGER.debug("Unknown page visibility value from client: {}",
+                    value);
+        }
+    }
+
     /**
      * Opens the given url in a new tab.
      *

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

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.component.page;
+
+/**
+ * Represents the visibility state of a browser page.
+ * <p>
+ * Uses the browser's Page Visibility API ({@code document.hidden}) combined
+ * with {@code document.hasFocus()} to distinguish between three observable
+ * states — fully visible and focused, visible but not focused, and hidden —
+ * plus an {@link #UNKNOWN} sentinel used before the first value has arrived
+ * from the client.
+ *
+ * @see Page#pageVisibilitySignal()
+ */
+public enum PageVisibility {
+
+    /**
+     * No value has been reported by the browser yet. Used only as the initial
+     * value of the signal before the first client handshake delivers the real
+     * one. In normal request handling the signal is seeded before any user code
+     * (UI initialization, {@code UIInitListener}, component attach) runs, so
+     * this value is essentially never observed in practice; once a real value
+     * has arrived, the signal never returns to {@code UNKNOWN}.
+     */
+    UNKNOWN,
+
+    /**
+     * The page is visible and focused.
+     * <p>
+     * In the browser, this means {@code !document.hidden} and
+     * {@code document.hasFocus()} is {@code true}.
+     */
+    VISIBLE,
+
+    /**
+     * The page is visible but not focused, e.g. behind another window.
+     * <p>
+     * In the browser, this means {@code !document.hidden} and
+     * {@code document.hasFocus()} is {@code false}.
+     */
+    VISIBLE_NOT_FOCUSED,
+
+    /**
+     * The page is not visible, e.g. the browser tab is in the background or the
+     * window is minimized.
+     * <p>
+     * In the browser, this is indicated by {@code document.hidden} being
+     * {@code true}.
+     */
+    HIDDEN
+}

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

@@ -0,0 +1,97 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.component.page;
+
+import org.junit.jupiter.api.Test;
+import tools.jackson.databind.node.ObjectNode;
+
+import com.vaadin.flow.dom.DomEvent;
+import com.vaadin.flow.internal.JacksonUtils;
+import com.vaadin.flow.internal.nodefeature.ElementListenerMap;
+import com.vaadin.flow.shared.JsonConstants;
+import com.vaadin.flow.signals.Signal;
+import com.vaadin.flow.signals.local.ValueSignal;
+import com.vaadin.tests.util.MockUI;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertSame;
+
+class PageVisibilitySignalTest {
+
+    @Test
+    void pageVisibilitySignal_isReadOnly() {
+        MockUI ui = new MockUI();
+        Signal<PageVisibility> signal = ui.getPage().pageVisibilitySignal();
+        assertFalse(signal instanceof ValueSignal,
+                "pageVisibilitySignal() should return a read-only signal");
+    }
+
+    @Test
+    void pageVisibilitySignal_defaultsToUnknownBeforeBootstrap() {
+        MockUI ui = new MockUI();
+        Signal<PageVisibility> signal = ui.getPage().pageVisibilitySignal();
+        assertEquals(PageVisibility.UNKNOWN, signal.peek(),
+                "Before bootstrap the value should be UNKNOWN so callers can "
+                        + "distinguish 'no data yet' from a real VISIBLE");
+    }
+
+    @Test
+    void pageVisibilitySignal_readonlyWrapperIsCached() {
+        Page page = new MockUI().getPage();
+        assertSame(page.pageVisibilitySignal(), page.pageVisibilitySignal(),
+                "Repeated calls must return the same read-only wrapper so "
+                        + "subscriber identity stays stable");
+    }
+
+    @Test
+    void pageVisibilitySignal_tracksVisibilityChanges() {
+        MockUI ui = new MockUI();
+        Signal<PageVisibility> signal = ui.getPage().pageVisibilitySignal();
+
+        fireVisibilityEvent(ui, "VISIBLE");
+        assertEquals(PageVisibility.VISIBLE, signal.peek());
+
+        fireVisibilityEvent(ui, "HIDDEN");
+        assertEquals(PageVisibility.HIDDEN, signal.peek());
+
+        fireVisibilityEvent(ui, "VISIBLE_NOT_FOCUSED");
+        assertEquals(PageVisibility.VISIBLE_NOT_FOCUSED, signal.peek());
+    }
+
+    @Test
+    void pageVisibilitySignal_unknownDetailKeepsPreviousValue() {
+        MockUI ui = new MockUI();
+        Signal<PageVisibility> signal = ui.getPage().pageVisibilitySignal();
+
+        fireVisibilityEvent(ui, "VISIBLE");
+        fireVisibilityEvent(ui, "SOMETHING_NEW");
+
+        assertEquals(PageVisibility.VISIBLE, signal.peek(),
+                "Unknown detail values from a newer client should not reset "
+                        + "the signal");
+    }
+
+    private void fireVisibilityEvent(MockUI ui, String visibility) {
+        ObjectNode eventData = JacksonUtils.createObjectNode();
+        eventData.put("event.detail", visibility);
+        eventData.put(JsonConstants.EVENT_DATA_PHASE,
+                JsonConstants.EVENT_PHASE_TRAILING);
+        ui.getElement().getNode().getFeature(ElementListenerMap.class)
+                .fireEvent(new DomEvent(ui.getElement(),
+                        "vaadin-page-visibility-change", eventData));
+    }
+}