useIdle

1"use client"
2 
3import * as React from "react"
4 
5export interface UseIdleOptions {
6  /** Activity events to listen for, attached to `window` as passive. Passing this replaces the default list wholesale. */
7  events?: string[]
8  /** Initial idle value at mount. Default `false` — treated as "activity just happened". */
9  initialState?: boolean
10}
11 
12const DEFAULT_EVENTS = ["pointermove", "pointerdown", "keydown", "wheel", "touchstart"]
13 
14// high-frequency events (pointermove/wheel) reach handleActivity on every tick; a
15// clearTimeout + setTimeout per tick costs real time with many listeners or on a weak
16// device. Throttle by timestamp comparison instead: activity inside the window is
17// dropped and only the first activity past it resets the timer. The cost is that idle
18// can fire up to one window early, which is fine for idle detection.
19// the window has to narrow with timeout: a fixed 1s would call continuous activity idle
20// whenever timeout < 1s (the 500ms timer expires first, while the next activity let
21// through has to wait for 1s).
22const throttleFor = (timeout: number) => Math.min(1000, Math.max(100, Math.floor(timeout / 3)))
23 
24/**
25 * User idle detection. Mounting starts a `timeout` ms timer; any of `events` (pointer
26 * move/down, keyboard, wheel, touch by default) counts as activity — it sets `idle`
27 * to `false` and restarts the timer, and the timer expiring sets it to `true`.
28 *
29 * `visibilitychange` is handled separately and cannot be switched off through
30 * `events`: coming back to the tab (`document.visibilityState === "visible"`) counts
31 * as activity and resets the timer, but leaving it (hidden) does **not** force idle —
32 * the timer keeps counting real elapsed time and flips on its own, with no "away means
33 * idle" special case (a background tab's timer may be throttled and fire late; that
34 * drift is accepted rather than chased second by second).
35 *
36 * Every `setState` happens in an event or timer callback, never during render or
37 * synchronously in an effect body, so it is SSR-safe; unmount clears the timer and
38 * every listener.
39 */
40export function useIdle(timeout = 60000, options: UseIdleOptions = {}): boolean {
41  const { events = DEFAULT_EVENTS, initialState = false } = options
42  const [idle, setIdle] = React.useState(initialState)
43 
44  // latest events in a ref; the effect depends on eventsKey below (contents, not the
45  // array identity), so an inline array literal from a consumer does not tear the
46// … truncated