Jyotisha/frontend/src/hooks/use-visibility-aware-poll.ts

/**
 * Interval polling that stops while the tab is hidden.
 *
 * While `document.hidden` is true the interval is torn down entirely, so a
 * backgrounded tab or a locked phone issues no requests. Becoming visible
 * again fires one immediate poll (unless `refreshOnVisible` is false) and then
 * restarts the interval, so a returning user sees fresh state without waiting
 * out a full tick. The callback is held in a ref, so a caller may pass an
 * inline closure without restarting the interval on every render.
 */

"use client";

import { useEffect, useRef } from "react";

export type VisibilityAwarePollOptions = {
  readonly enabled: boolean;
  readonly intervalMs: number;
  readonly onPoll: () => void;
  readonly refreshOnVisible?: boolean;
};

export function useVisibilityAwarePoll(options: VisibilityAwarePollOptions): void {
  const { enabled, intervalMs, onPoll, refreshOnVisible = true } = options;
  const pollRef = useRef(onPoll);

  useEffect(() => {
    pollRef.current = onPoll;
  }, [onPoll]);

  useEffect(() => {
    if (!enabled || typeof document === "undefined" || intervalMs <= 0) {
      return;
    }

    let timer: number | null = null;

    const stop = () => {
      if (timer !== null) {
        window.clearInterval(timer);
        timer = null;
      }
    };

    const start = () => {
      stop();
      timer = window.setInterval(() => pollRef.current(), intervalMs);
    };

    const handleVisibilityChange = () => {
      if (document.hidden) {
        stop();
        return;
      }
      if (refreshOnVisible) {
        pollRef.current();
      }
      start();
    };

    if (!document.hidden) {
      start();
    }
    document.addEventListener("visibilitychange", handleVisibilityChange);

    return () => {
      stop();
      document.removeEventListener("visibilitychange", handleVisibilityChange);
    };
  }, [enabled, intervalMs, refreshOnVisible]);
}