detect-tab/src/types.ts

A comprehensive tab detection and management library for web applications

/**
 * Tab visibility states
 */
export enum TabState {
  VISIBLE = 'visible',
  HIDDEN = 'hidden',
  PRERENDER = 'prerender',
  UNLOADED = 'unloaded'
}

/**
 * Tab events that can be listened to
 */
export enum TabEvent {
  VISIBILITY_CHANGE = 'visibilitychange',
  FOCUS = 'focus',
  BLUR = 'blur',
  BEFORE_UNLOAD = 'beforeunload',
  UNLOAD = 'unload',
  PAGE_SHOW = 'pageshow',
  PAGE_HIDE = 'pagehide'
}

/**
 * Configuration options for DetectTab
 */
export interface DetectTabOptions {
  /** Enable automatic event listeners */
  autoStart?: boolean;
  /** Debounce time for rapid events (in milliseconds) */
  debounceTime?: number;
  /** Enable logging for debugging */
  debug?: boolean;
  /** Custom storage key for persistence */
  storageKey?: string;
  /** Enable persistence across sessions */
  persistent?: boolean;
}

/**
 * Tab information interface
 */
export interface TabInfo {
  /** Current visibility state */
  state: TabState;
  /** Whether the tab is currently focused */
  focused: boolean;
  /** Whether the tab is visible */
  visible: boolean;
  /** Timestamp of last state change */
  lastChanged: number;
  /** Time spent in current state (milliseconds) */
  timeInState: number;
  /** Total time spent visible (milliseconds) */
  totalVisibleTime: number;
  /** Total time spent hidden (milliseconds) */
  totalHiddenTime: number;
  /** Number of visibility changes */
  visibilityChanges: number;
}

/**
 * Event callback types
 */
export type TabEventCallback = (info: TabInfo) => void;
export type TabStateChangeCallback = (state: TabState, info: TabInfo) => void;
export type TabFocusCallback = (focused: boolean, info: TabInfo) => void;