@supunlakmal/hooks
Version:
A collection of reusable React hooks
67 lines (66 loc) • 2.59 kB
TypeScript
type UserIdleState = 'active' | 'idle';
type ScreenIdleState = 'locked' | 'unlocked';
type IdlePermissionState = 'granted' | 'denied' | 'prompt';
declare global {
interface IdleDetector {
readonly userState: UserIdleState;
readonly screenState: ScreenIdleState;
onchange: ((this: IdleDetector, ev: Event) => any) | null;
start: (options?: {
threshold?: number;
signal?: AbortSignal;
}) => Promise<void>;
}
interface IdleDetectorOptions {
threshold?: number;
signal?: AbortSignal;
}
interface Window {
IdleDetector: {
prototype: IdleDetector;
new (): IdleDetector;
requestPermission: () => Promise<IdlePermissionState>;
};
}
}
interface UseIdleDetectionOptions {
/** Threshold in milliseconds to consider the user idle. Defaults to 60000 (1 minute). */
threshold?: number;
/** Optional: AbortSignal to stop the detector externally. */
signal?: AbortSignal;
/** Optional: Callback when idle state changes. */
onChange?: (states: {
userState: UserIdleState;
screenState: ScreenIdleState;
}) => void;
/** Optional: Callback on error. */
onError?: (error: Error) => void;
/** If true, automatically attempts to start the detector on mount after requesting permission. Defaults to true. */
autoStart?: boolean;
}
interface UseIdleDetectionReturn {
/** Current user state ('active' or 'idle'). */
userState: UserIdleState | null;
/** Current screen state ('locked' or 'unlocked'). */
screenState: ScreenIdleState | null;
/** Current permission status for idle detection. */
permissionState: IdlePermissionState | null;
/** Indicates if the detector is currently active and listening for changes. */
isActive: boolean;
/** Error object if permission request or detection fails. */
error: Error | null;
/** Function to request permission for idle detection. */
requestPermission: () => Promise<IdlePermissionState>;
/** Function to start the idle detector. */
startDetector: () => Promise<void>;
/** Indicates if the Idle Detection API is supported by the browser. */
isSupported: boolean;
}
/**
* Hook to detect user idle state and screen lock status using the Idle Detection API.
*
* @param options Configuration options for the idle detector.
* @returns State and controls for idle detection.
*/
export declare function useIdleDetection(options?: UseIdleDetectionOptions): UseIdleDetectionReturn;
export {};