react-realtime-hooks 1.0.4 → 1.2.0

package/README.md

@@ -7,9 +7,9 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-typed-3178c6)](https://www.typescriptlang.org/)
 [![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 and connection gating.
 
-`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, page visibility, and connection gating, 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,8 @@ 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
+- environment-aware connection gating for offline state and background tabs
 - typed message parsing and sending
 
 `react-realtime-hooks` packages those concerns into small hooks that compose cleanly in React.
@@ -33,6 +34,7 @@ Real apps need:
 - `useWebSocket` and `useEventSource` return state you can render, not just transport instances.
 - Built-in reconnect flow with exponential backoff, jitter, attempt limits, and manual restart.
 - Heartbeat support with ack matching, timeout detection, and latency measurement.
+- `useConnectionGate` turns online and visibility signals into a single `connect` flag for transport hooks.
 - Discriminated connection snapshots: `idle`, `connecting`, `open`, `reconnecting`, `closing`, `closed`, `error`.
 - First-class TypeScript support with generic message types and custom parsers/serializers.
 - SSR-safe by default. No browser-only globals are touched during server render.
@@ -46,7 +48,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`, `usePageVisibility`, and `useConnectionGate` for browser-aware 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        |
 
@@ -65,7 +67,11 @@ Peer dependency:
 ## 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 +81,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 +100,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 +153,7 @@ Browser APIs
   WebSocket / EventSource / navigator.onLine
 
 Core hooks
-  useReconnect / useHeartbeat / useOnlineStatus
+  useReconnect / useHeartbeat / useOnlineStatus / usePageVisibility / useConnectionGate
 
 Transport hooks
   useWebSocket / useEventSource
@@ -204,7 +211,9 @@ This library already models those edges in a reusable way.
 | `useEventSource`  | Server-Sent Events streams           | `status`, `eventSource`, `lastMessage`, `lastEventName`, `reconnect()`       |
 | `useReconnect`    | Reusable retry and backoff logic     | `schedule()`, `cancel()`, `reset()`, `attempt`, `status`                     |
 | `useHeartbeat`    | Liveness checks and timeout tracking | `start()`, `stop()`, `beat()`, `notifyAck()`, `latencyMs`                    |
+| `useConnectionGate` | Browser-aware transport gating     | `connect`, `reason`, `isBlocked`, gate transition timestamps                 |
 | `useOnlineStatus` | Browser online/offline state         | `isOnline`, `isSupported`, transition timestamps                             |
+| `usePageVisibility` | Browser tab/page visibility state  | `isVisible`, `visibilityState`, `isSupported`, transition timestamps         |
 
 ## Transport Examples
 
@@ -334,6 +343,50 @@ 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>
+  );
+}
+```
+### `useConnectionGate`
+
+```tsx
+import { useConnectionGate, useWebSocket } from "react-realtime-hooks";
+
+export function GatedNotifications() {
+  const gate = useConnectionGate({
+    requireOnline: true,
+    requireVisible: true,
+    hiddenGraceMs: 30_000,
+  });
+  const socket = useWebSocket({
+    connect: gate.connect,
+    reconnect: {
+      initialDelayMs: 1_000,
+      maxAttempts: null,
+    },
+    url: "ws://localhost:8080/notifications",
+  });
+
+  return (
+    <div>
+      Gate: {gate.reason} | Transport: {socket.status}
+    </div>
+  );
+}
+```
 ## API Reference
 
 <details>
@@ -486,6 +539,42 @@ When you configure `useWebSocket` heartbeat, you can also set `timeoutAction` an
 
 </details>
 
+<details>
+<summary><strong>useConnectionGate</strong></summary>
+
+### Options
+
+| Option             | Type      | Default | Description                                                        |
+| ------------------ | --------- | ------- | ------------------------------------------------------------------ |
+| `enabled`          | `boolean` | `true`  | Master on/off switch for the gate                                  |
+| `requireOnline`    | `boolean` | `true`  | Blocks `connect` when the browser reports offline                  |
+| `requireVisible`   | `boolean` | `false` | Blocks `connect` when the page is hidden                           |
+| `hiddenGraceMs`    | `number`  | `0`     | Delay before hidden pages are blocked                              |
+| `initialOnline`    | `boolean` | `true`  | Fallback value when `navigator.onLine` is unavailable              |
+| `initialVisible`   | `boolean` | `true`  | Fallback value when the Visibility API is unavailable              |
+| `trackTransitions` | `boolean` | `true`  | Tracks `lastChangedAt`, `becameReadyAt`, and `becameBlockedAt`     |
+
+### Result
+
+| Field                      | Type                                       | Description                                                |
+| -------------------------- | ------------------------------------------ | ---------------------------------------------------------- |
+| `connect`                  | `boolean`                                  | Flag to pass into `useWebSocket` or `useEventSource`       |
+| `isBlocked`                | `boolean`                                  | Whether the gate is currently blocking connection          |
+| `reason`                   | `"ready" \| "manual" \| "offline" \| "hidden"` | Current gate reason                                        |
+| `isWaitingForVisibleGrace` | `boolean`                                  | `true` while a hidden-tab grace window is still active     |
+| `isOnline`                 | `boolean`                                  | Current browser online state                               |
+| `isOnlineSupported`        | `boolean`                                  | Whether `navigator.onLine` is available                    |
+| `isVisible`                | `boolean`                                  | Whether the current page is visible                        |
+| `isVisibilitySupported`    | `boolean`                                  | Whether `document.visibilityState` is available            |
+| `visibilityState`          | `DocumentVisibilityState \| "visible"`   | Current browser visibility state                           |
+| `lastChangedAt`            | `number \| null`                          | Timestamp of the last gate state change                    |
+| `becameReadyAt`            | `number \| null`                          | Timestamp of the last transition into `reason === "ready"` |
+| `becameBlockedAt`          | `number \| null`                          | Timestamp of the last transition into a blocked state      |
+
+`reason` priority is deterministic: `manual` overrides `offline`, and `offline` overrides `hidden`.
+That keeps the gate predictable when multiple blockers apply at once.
+
+</details>
 <details>
 <summary><strong>useOnlineStatus</strong></summary>
 
@@ -508,6 +597,28 @@ 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.
@@ -527,7 +638,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
 
@@ -551,3 +662,8 @@ 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,227 @@ 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/timers.ts
+var sanitizeTimerDelay = (delayMs) => {
+  if (!Number.isFinite(delayMs)) {
+    return 0;
+  }
+  return Math.max(0, Math.round(delayMs));
+};
+var createManagedTimeout = () => {
+  let timeoutId = null;
+  return {
+    cancel() {
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+    },
+    isActive() {
+      return timeoutId !== null;
+    },
+    schedule(callback, delayMs) {
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+      }
+      timeoutId = setTimeout(() => {
+        timeoutId = null;
+        callback();
+      }, sanitizeTimerDelay(delayMs));
+    }
+  };
+};
+var createManagedInterval = () => {
+  let intervalId = null;
+  return {
+    cancel() {
+      if (intervalId !== null) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+    },
+    isActive() {
+      return intervalId !== null;
+    },
+    start(callback, intervalMs) {
+      if (intervalId !== null) {
+        clearInterval(intervalId);
+      }
+      intervalId = setInterval(callback, sanitizeTimerDelay(intervalMs));
+    }
+  };
+};
+
+// src/hooks/useConnectionGate.ts
+var createEmptyTransitionState3 = () => ({
+  becameBlockedAt: null,
+  becameReadyAt: null,
+  lastChangedAt: null
+});
+var normalizeHiddenGraceMs = (value) => {
+  if (value === void 0 || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, value);
+};
+var useConnectionGate = (options = {}) => {
+  const enabled = options.enabled ?? true;
+  const requireOnline = options.requireOnline ?? true;
+  const requireVisible = options.requireVisible ?? false;
+  const hiddenGraceMs = normalizeHiddenGraceMs(options.hiddenGraceMs);
+  const trackTransitions = options.trackTransitions ?? true;
+  const onlineStatus = useOnlineStatus({
+    ...options.initialOnline === void 0 ? {} : { initialOnline: options.initialOnline },
+    trackTransitions: false
+  });
+  const pageVisibility = usePageVisibility({
+    ...options.initialVisible === void 0 ? {} : { initialVisible: options.initialVisible },
+    trackTransitions: false
+  });
+  const hiddenGraceTimeoutRef = react.useRef(createManagedTimeout());
+  const hiddenSinceRef = react.useRef(null);
+  const previousStateRef = react.useRef(null);
+  const [hasExceededHiddenGrace, setHasExceededHiddenGrace] = react.useState(false);
+  const [isWaitingForVisibleGrace, setIsWaitingForVisibleGrace] = react.useState(false);
+  const [transitions, setTransitions] = react.useState(createEmptyTransitionState3);
+  react.useEffect(() => () => {
+    hiddenGraceTimeoutRef.current.cancel();
+  }, []);
+  react.useEffect(() => {
+    hiddenGraceTimeoutRef.current.cancel();
+    if (!requireVisible || pageVisibility.isVisible) {
+      hiddenSinceRef.current = null;
+      setHasExceededHiddenGrace(false);
+      setIsWaitingForVisibleGrace(false);
+      return;
+    }
+    const hiddenSince = hiddenSinceRef.current ?? Date.now();
+    hiddenSinceRef.current = hiddenSince;
+    if (hiddenGraceMs <= 0) {
+      setHasExceededHiddenGrace(true);
+      setIsWaitingForVisibleGrace(false);
+      return;
+    }
+    const elapsedMs = Date.now() - hiddenSince;
+    if (elapsedMs >= hiddenGraceMs) {
+      setHasExceededHiddenGrace(true);
+      setIsWaitingForVisibleGrace(false);
+      return;
+    }
+    setHasExceededHiddenGrace(false);
+    setIsWaitingForVisibleGrace(true);
+    hiddenGraceTimeoutRef.current.schedule(() => {
+      setHasExceededHiddenGrace(true);
+      setIsWaitingForVisibleGrace(false);
+    }, hiddenGraceMs - elapsedMs);
+  }, [hiddenGraceMs, pageVisibility.isVisible, requireVisible]);
+  let reason = "ready";
+  if (!enabled) {
+    reason = "manual";
+  } else if (requireOnline && !onlineStatus.isOnline) {
+    reason = "offline";
+  } else if (requireVisible && !pageVisibility.isVisible && hasExceededHiddenGrace) {
+    reason = "hidden";
+  }
+  const connect = reason === "ready";
+  const isBlocked = !connect;
+  react.useEffect(() => {
+    if (!trackTransitions) {
+      previousStateRef.current = {
+        connect,
+        reason
+      };
+      setTransitions(createEmptyTransitionState3);
+      return;
+    }
+    const previousState = previousStateRef.current;
+    if (previousState === null) {
+      previousStateRef.current = {
+        connect,
+        reason
+      };
+      return;
+    }
+    if (previousState.connect === connect && previousState.reason === reason) {
+      return;
+    }
+    const changedAt = Date.now();
+    previousStateRef.current = {
+      connect,
+      reason
+    };
+    setTransitions((current) => ({
+      becameBlockedAt: connect ? current.becameBlockedAt : changedAt,
+      becameReadyAt: connect ? changedAt : current.becameReadyAt,
+      lastChangedAt: changedAt
+    }));
+  }, [connect, reason, trackTransitions]);
+  return {
+    becameBlockedAt: transitions.becameBlockedAt,
+    becameReadyAt: transitions.becameReadyAt,
+    connect,
+    isBlocked,
+    isOnline: onlineStatus.isOnline,
+    isOnlineSupported: onlineStatus.isSupported,
+    isVisibilitySupported: pageVisibility.isSupported,
+    isVisible: pageVisibility.isVisible,
+    isWaitingForVisibleGrace,
+    lastChangedAt: transitions.lastChangedAt,
+    reason,
+    visibilityState: pageVisibility.visibilityState
+  };
+};
 
 // src/core/reconnect.ts
 var DEFAULT_RECONNECT_OPTIONS = {
@@ -209,57 +445,6 @@ var createReconnectAttempt = (attempt, trigger, options, lastDelayMs, config = {
   };
 };
 
-// src/core/timers.ts
-var sanitizeTimerDelay = (delayMs) => {
-  if (!Number.isFinite(delayMs)) {
-    return 0;
-  }
-  return Math.max(0, Math.round(delayMs));
-};
-var createManagedTimeout = () => {
-  let timeoutId = null;
-  return {
-    cancel() {
-      if (timeoutId !== null) {
-        clearTimeout(timeoutId);
-        timeoutId = null;
-      }
-    },
-    isActive() {
-      return timeoutId !== null;
-    },
-    schedule(callback, delayMs) {
-      if (timeoutId !== null) {
-        clearTimeout(timeoutId);
-      }
-      timeoutId = setTimeout(() => {
-        timeoutId = null;
-        callback();
-      }, sanitizeTimerDelay(delayMs));
-    }
-  };
-};
-var createManagedInterval = () => {
-  let intervalId = null;
-  return {
-    cancel() {
-      if (intervalId !== null) {
-        clearInterval(intervalId);
-        intervalId = null;
-      }
-    },
-    isActive() {
-      return intervalId !== null;
-    },
-    start(callback, intervalMs) {
-      if (intervalId !== null) {
-        clearInterval(intervalId);
-      }
-      intervalId = setInterval(callback, sanitizeTimerDelay(intervalMs));
-    }
-  };
-};
-
 // src/hooks/useReconnect.ts
 var createInitialState = (enabled) => ({
   attempt: 0,
@@ -1395,9 +1580,11 @@ var useEventSource = (options) => {
   };
 };
 
+exports.useConnectionGate = useConnectionGate;
 exports.useEventSource = useEventSource;
 exports.useHeartbeat = useHeartbeat;
 exports.useOnlineStatus = useOnlineStatus;
+exports.usePageVisibility = usePageVisibility;
 exports.useReconnect = useReconnect;
 exports.useWebSocket = useWebSocket;
 //# sourceMappingURL=index.cjs.map