react-realtime-hooks 1.0.3 → 1.1.0

package/README.md

@@ -5,11 +5,11 @@
 [![Demo](https://img.shields.io/github/actions/workflow/status/volkov85/react-realtime-hooks/pages.yml?branch=main&label=demo)](https://github.com/volkov85/react-realtime-hooks/actions/workflows/pages.yml)
 [![license](https://img.shields.io/npm/l/react-realtime-hooks)](https://github.com/volkov85/react-realtime-hooks/blob/main/LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-typed-3178c6)](https://www.typescriptlang.org/)
-[![react](https://img.shields.io/badge/react-18.3%2B%20%7C%2019-149eca)](https://www.npmjs.com/package/react)
+[![react](https://img.shields.io/badge/react-19.x-149eca)](https://www.npmjs.com/package/react)
 
-Production-ready React hooks for WebSocket and SSE with auto-reconnect, heartbeat, typed connection state, and browser network awareness.
+Production-ready React hooks for WebSocket and SSE with auto-reconnect, heartbeat, typed connection state, and browser network awareness including page visibility.
 
-`react-realtime-hooks` is for apps that need more than "open a socket and hope for the best". It gives you composable hooks for transport lifecycle, retry strategy, heartbeat, and online status, so your UI can react to realtime state without rebuilding the same connection logic in every screen.
+`react-realtime-hooks` is for apps that need more than "open a socket and hope for the best". It gives you composable hooks for transport lifecycle, retry strategy, heartbeat, online status, and page visibility, so your UI can react to realtime state without rebuilding the same connection logic in every screen.
 
 Live demo: https://volkov85.github.io/react-realtime-hooks/
 
@@ -23,7 +23,7 @@ Real apps need:
 - reconnect strategy with caps, jitter, and manual control
 - heartbeat and timeout tracking
 - clean SSR behavior
-- browser network awareness
+- browser network and page visibility awareness
 - typed message parsing and sending
 
 `react-realtime-hooks` packages those concerns into small hooks that compose cleanly in React.
@@ -46,7 +46,7 @@ Real apps need:
 | Connection state  | You model it yourself              | Built-in status model you can render directly    |
 | Reconnect flow    | Manual timers and teardown         | `useReconnect` with backoff, jitter, and limits  |
 | Heartbeat         | Custom ping/pong loop              | `heartbeat` support with timeout and latency     |
-| Network awareness | Separate browser event wiring      | `useOnlineStatus` for online/offline state       |
+| Browser awareness | Separate browser event wiring      | `useOnlineStatus` and `usePageVisibility` for browser state |
 | SSR safety        | Easy to break during render        | Browser-only behavior stays out of server render |
 | UI ergonomics     | Event handlers and refs everywhere | Hook result already shaped for product UI        |
 
@@ -60,12 +60,16 @@ npm install react-realtime-hooks
 
 Peer dependency:
 
-- `react@^18.3.0 || ^19.0.0`
+- `react@^19.0.0`
 
 ## How It Feels
 
 ```tsx
-import { useOnlineStatus, useWebSocket } from "react-realtime-hooks";
+import {
+  useOnlineStatus,
+  usePageVisibility,
+  useWebSocket
+} from "react-realtime-hooks";
 
 type IncomingMessage =
   | { type: "notification"; text: string }
@@ -75,6 +79,7 @@ type OutgoingMessage = { type: "ack"; id: string } | { type: "ping" };
 
 export function NotificationsPanel() {
   const network = useOnlineStatus();
+  const page = usePageVisibility();
   const socket = useWebSocket<IncomingMessage, OutgoingMessage>({
     url: "ws://localhost:8080/notifications",
     parseMessage: (event) => JSON.parse(String(event.data)) as IncomingMessage,
@@ -93,8 +98,8 @@ export function NotificationsPanel() {
   return (
     <section>
       <p>
-        Network: {network.isOnline ? "online" : "offline"} | Transport:{" "}
-        {socket.status}
+        Page: {page.isVisible ? "visible" : "hidden"} | Network:{" "}
+        {network.isOnline ? "online" : "offline"} | Transport: {socket.status}
       </p>
 
       {socket.status === "reconnecting" && (
@@ -146,7 +151,7 @@ Browser APIs
   WebSocket / EventSource / navigator.onLine
 
 Core hooks
-  useReconnect / useHeartbeat / useOnlineStatus
+  useReconnect / useHeartbeat / useOnlineStatus / usePageVisibility
 
 Transport hooks
   useWebSocket / useEventSource
@@ -205,6 +210,7 @@ This library already models those edges in a reusable way.
 | `useReconnect`    | Reusable retry and backoff logic     | `schedule()`, `cancel()`, `reset()`, `attempt`, `status`                     |
 | `useHeartbeat`    | Liveness checks and timeout tracking | `start()`, `stop()`, `beat()`, `notifyAck()`, `latencyMs`                    |
 | `useOnlineStatus` | Browser online/offline state         | `isOnline`, `isSupported`, transition timestamps                             |
+| `usePageVisibility` | Browser tab/page visibility state  | `isVisible`, `visibilityState`, `isSupported`, transition timestamps         |
 
 ## Transport Examples
 
@@ -334,6 +340,23 @@ export function NetworkIndicator() {
 }
 ```
 
+### `usePageVisibility`
+
+```tsx
+import { usePageVisibility } from "react-realtime-hooks";
+
+export function AttentionAwareBadge() {
+  const page = usePageVisibility({
+    trackTransitions: true,
+  });
+
+  return (
+    <span>
+      {page.isVisible ? "Active tab" : "Background tab"} ({page.visibilityState})
+    </span>
+  );
+}
+```
 ## API Reference
 
 <details>
@@ -354,7 +377,7 @@ export function NetworkIndicator() {
 | `shouldReconnect`  | `(event) => boolean`           | `true`                     | Reconnect gate on close            |
 | `onOpen`           | `(event, socket) => void`      | `undefined`                | Open callback                      |
 | `onMessage`        | `(message, event) => void`     | `undefined`                | Message callback                   |
-| `onError`          | `(event) => void`              | `undefined`                | Error callback                     |
+| `onError`          | `(event) => void`              | `undefined`                | Called for transport, heartbeat, and parse errors |
 | `onClose`          | `(event) => void`              | `undefined`                | Close callback                     |
 
 ### Result
@@ -397,7 +420,7 @@ When you configure `useWebSocket` heartbeat, you can also set `timeoutAction` an
 | `shouldReconnect` | `(event) => boolean`                  | `true`           | Reconnect gate on error             |
 | `onOpen`          | `(event, source) => void`             | `undefined`      | Open callback                       |
 | `onMessage`       | `(message, event) => void`            | `undefined`      | Default `message` callback          |
-| `onError`         | `(event) => void`                     | `undefined`      | Error callback                      |
+| `onError`         | `(event) => void`                     | `undefined`      | Called for transport and parse errors |
 | `onEvent`         | `(eventName, message, event) => void` | `undefined`      | Named event callback                |
 
 ### Result
@@ -508,11 +531,34 @@ When you configure `useWebSocket` heartbeat, you can also set `timeoutAction` an
 
 </details>
 
+<details>
+<summary><strong>usePageVisibility</strong></summary>
+
+### Options
+
+| Option             | Type      | Default | Description                                                 |
+| ------------------ | --------- | ------- | ----------------------------------------------------------- |
+| `initialVisible`   | `boolean` | `true`  | Fallback value when the Visibility API is unavailable       |
+| `trackTransitions` | `boolean` | `true`  | Tracks `lastChangedAt`, `becameVisibleAt`, `becameHiddenAt` |
+
+### Result
+
+| Field             | Type                                 | Description                                      |
+| ----------------- | ------------------------------------ | ------------------------------------------------ |
+| `isVisible`       | `boolean`                            | Whether the current page is visible              |
+| `visibilityState` | `DocumentVisibilityState \| "visible"` | Current browser visibility state                 |
+| `isSupported`     | `boolean`                            | Whether `document.visibilityState` is available  |
+| `lastChangedAt`   | `number \| null`                    | Timestamp of the last visibility transition      |
+| `becameVisibleAt` | `number \| null`                    | Timestamp of the last visible transition         |
+| `becameHiddenAt`  | `number \| null`                    | Timestamp of the last hidden transition          |
+
+</details>
 ## Limitations And Edge Cases
 
 - `useEventSource` is receive-only by design. SSE is not a bidirectional transport.
 - `useWebSocket` heartbeat support is client-side. You still define your own server ping/pong protocol.
-- If `parseMessage` throws, the hook closes the current transport, moves into `error`, stores `lastError`, and stops auto-reconnect until manual `open()` or `reconnect()`.
+- If `parseMessage` throws, the hook calls `onError`, closes the current transport, moves into `error`, stores `lastError`, and stops auto-reconnect until manual `open()` or `reconnect()`.
+- Stopping heartbeat clears timeout state and the previous beat/ack timestamps so a new session starts with fresh metrics.
 - `connect: false` keeps the hook in `idle` until `open()` is called.
 - Manual `close()` is sticky. The hook stays closed until `open()` or `reconnect()` is called.
 - No transport polyfills are bundled. Provide your own runtime support where needed.
@@ -526,7 +572,7 @@ The package includes behavior tests for:
 - exponential backoff
 - timer and listener cleanup
 - heartbeat start / stop / timeout
-- browser offline / online transitions
+- browser offline / online and page visibility transitions
 - invalid payload and parse errors
 - manual reconnect and manual close
 
@@ -550,3 +596,7 @@ Development and release workflow live in [CONTRIBUTING.md](./CONTRIBUTING.md).
 ## License
 
 MIT
+
+
+
+

package/dist/index.cjs

@@ -8,6 +8,7 @@ var react = require('react');
 var isWebSocketSupported = () => typeof WebSocket !== "undefined";
 var isEventSourceSupported = () => typeof EventSource !== "undefined";
 var hasNavigatorOnLineSupport = () => typeof navigator !== "undefined" && typeof navigator.onLine === "boolean";
+var hasDocumentVisibilitySupport = () => typeof document !== "undefined" && typeof document.visibilityState === "string";
 var readOnlineStatus = (initialOnline = true) => {
   if (!hasNavigatorOnLineSupport()) {
     return {
@@ -20,6 +21,20 @@ var readOnlineStatus = (initialOnline = true) => {
     isSupported: true
   };
 };
+var readPageVisibility = (initialVisible = true) => {
+  if (!hasDocumentVisibilitySupport()) {
+    return {
+      isVisible: initialVisible,
+      isSupported: false,
+      visibilityState: initialVisible ? "visible" : "hidden"
+    };
+  }
+  return {
+    isVisible: document.visibilityState === "visible",
+    isSupported: true,
+    visibilityState: document.visibilityState
+  };
+};
 
 // src/hooks/useOnlineStatus.ts
 var subscribeToOnlineStatus = (onStoreChange) => {
@@ -72,6 +87,56 @@ var useOnlineStatus = (options = {}) => {
     ...transitions
   };
 };
+var subscribeToPageVisibility = (onStoreChange) => {
+  if (typeof document === "undefined" || !hasDocumentVisibilitySupport()) {
+    return () => {
+    };
+  }
+  document.addEventListener("visibilitychange", onStoreChange);
+  return () => {
+    document.removeEventListener("visibilitychange", onStoreChange);
+  };
+};
+var createEmptyTransitionState2 = () => ({
+  lastChangedAt: null,
+  becameHiddenAt: null,
+  becameVisibleAt: null
+});
+var usePageVisibility = (options = {}) => {
+  const initialVisible = options.initialVisible ?? true;
+  const trackTransitions = options.trackTransitions ?? true;
+  const visibilityState = react.useSyncExternalStore(
+    subscribeToPageVisibility,
+    () => readPageVisibility(initialVisible).visibilityState,
+    () => initialVisible ? "visible" : "hidden"
+  );
+  const isVisible = visibilityState === "visible";
+  const previousVisibleRef = react.useRef(isVisible);
+  const [transitions, setTransitions] = react.useState(createEmptyTransitionState2);
+  react.useEffect(() => {
+    if (!trackTransitions) {
+      previousVisibleRef.current = isVisible;
+      setTransitions(createEmptyTransitionState2);
+      return;
+    }
+    if (previousVisibleRef.current === isVisible) {
+      return;
+    }
+    const changedAt = Date.now();
+    previousVisibleRef.current = isVisible;
+    setTransitions((current) => ({
+      lastChangedAt: changedAt,
+      becameHiddenAt: isVisible ? current.becameHiddenAt : changedAt,
+      becameVisibleAt: isVisible ? changedAt : current.becameVisibleAt
+    }));
+  }, [isVisible, trackTransitions]);
+  return {
+    isSupported: hasDocumentVisibilitySupport(),
+    isVisible,
+    visibilityState,
+    ...transitions
+  };
+};
 
 // src/core/reconnect.ts
 var DEFAULT_RECONNECT_OPTIONS = {
@@ -488,11 +553,7 @@ var useHeartbeat = (options) => {
     generationRef.current += 1;
     intervalRef.current.cancel();
     timeoutRef.current.cancel();
-    commitState((current) => ({
-      ...current,
-      hasTimedOut: false,
-      isRunning: false
-    }));
+    commitState(createInitialState2(false));
   };
   const beat = () => {
     if (!enabled) {
@@ -747,6 +808,7 @@ var useWebSocket = (options) => {
   const applyHeartbeatAction = react.useEffectEvent(
     (action, error, reconnectTrigger) => {
       heartbeat.stop();
+      options.onError?.(error);
       if (action === "none") {
         commitState((current) => ({
           ...current,
@@ -824,6 +886,7 @@ var useWebSocket = (options) => {
       suppressReconnectRef.current = true;
       reconnect.cancel();
       heartbeat.stop();
+      options.onError?.(parseError);
       commitState((current) => ({
         ...current,
         lastChangedAt: Date.now(),
@@ -837,6 +900,7 @@ var useWebSocket = (options) => {
     heartbeat.stop();
     commitState((current) => ({
       ...current,
+      lastChangedAt: Date.now(),
       lastError: event,
       status: "error"
     }));
@@ -1183,6 +1247,7 @@ var useEventSource = (options) => {
         suppressReconnectRef.current = true;
         reconnect.cancel();
         closeEventSource();
+        options.onError?.(parseError);
         commitState((current) => ({
           ...current,
           lastChangedAt: Date.now(),
@@ -1398,6 +1463,7 @@ var useEventSource = (options) => {
 exports.useEventSource = useEventSource;
 exports.useHeartbeat = useHeartbeat;
 exports.useOnlineStatus = useOnlineStatus;
+exports.usePageVisibility = usePageVisibility;
 exports.useReconnect = useReconnect;
 exports.useWebSocket = useWebSocket;
 //# sourceMappingURL=index.cjs.map