TypeScript

ForesightJS is fully written in TypeScript, and all types are exported from @foresightjs/react:

import type { ForesightRegisterOptionsWithoutElement } from "@foresightjs/react"

The hooks are generic over the element type, so the returned ref is correctly typed:

const { elementRef } = useForesight<HTMLAnchorElement>({ callback })

Most Used Internal types

ForesightElementState

This is the main type used in ForesightJS: the flat, immutable state snapshot of a registered element. Your callback receives it, most events carry it as state, and register() returns it (plus a few functions, see ForesightRegisterResult). The reference is replaced on every change, never mutated.

type ForesightElementState = {
  id: string // unique id assigned during registration
  name: string // name visible in the devtools
  meta: Record<string, unknown> // your custom meta data
  elementBounds: {
    originalRect: DOMRectReadOnly
    hitSlop: Exclude<HitSlop, number>
    expandedRect: Readonly<Rect> // originalRect + hitSlop
  }
  isLimitedConnection: boolean
  isIntersectingWithViewport: boolean
  isRegistered: boolean
  isActive: boolean
  isParked: boolean // detached from the DOM, kept registered but inactive until it reconnects
  isEnabled: boolean
  isPredicted: boolean
  isCallbackRunning: boolean
  hitCount: number
  registerCount: number // amount of times this element has been (re)registered
  durationMs: number | undefined // duration of the most recent callback run
  status: "error" | "success" | undefined // status of the most recent callback
  error: string | null
  reactivateAfter: number
}

See the registration return value for what each field means.

ForesightRegisterResult

What ForesightManager.instance.register() returns: the element's state at registration time plus control functions.

type ForesightRegisterResult = ForesightElementState & {
  unregister: () => void
  subscribe: (listener: () => void) => () => void // returns an unsubscribe function
  getSnapshot: () => ForesightElementState // current state snapshot
}

CallbackHitType

type CallbackHitType =
  | { kind: "mouse"; subType: "hover" | "trajectory" }
  | { kind: "tab"; subType: "forwards" | "reverse" }
  | { kind: "scroll"; subType: "up" | "down" | "left" | "right" }
  | { kind: "touch"; subType?: string }
  | { kind: "viewport"; subType?: string }

CurrentDeviceStrategy

Represents the current input method being used. ForesightJS automatically detects and switches between strategies.

type CurrentDeviceStrategy = "mouse" | "touch" | "pen"

ForesightManagerData

Snapshot of the current ForesightManager state, including all global settings, registered elements, and interaction statistics. This is primarily used for debugging, monitoring, and development purposes.

This data is returned in the managerSettingsChanged event or by calling ForesightManager.instance.getManagerData manually.

type ForesightManagerData = {
  registeredElements: ReadonlyMap<ForesightElement, ForesightElementState> // See above for ForesightElementState
  globalSettings: Readonly<ForesightManagerSettings> // See configuration for global settings
  globalCallbackHits: Readonly<CallbackHits> // See above for CallbackHitType, this is that but all of them combined
  eventListeners: ReadonlyMap<keyof ForesightEventMap, ForesightEventListener[]> // All event listeners currently listening
  currentDeviceStrategy: CurrentDeviceStrategy
  activeElementCount: number
  parkedElementCount: number // elements detached from the DOM, waiting to reconnect
  loadedModules: ForesightModules // which handlers/predictors are lazily loaded
}

Helper Types

ForesightCallback

The callback function type used when registering elements. Receives the ForesightElementState of the element that triggered the callback.

type ForesightCallback = (state: ForesightElementState) => void

This is useful when registering multiple elements with a shared callback, as you can identify which element triggered it:

const myCallback: ForesightCallback = state => {
  console.log(`Triggered by: ${state.name}`)
}

ForesightRegisterOptionsWithoutElement

Useful for if you want to create a custom button component in a modern framework (for example React). And you want to have the ForesightRegisterOptions used in ForesightManager.instance.register({}) without the element as the element will be the ref of the component.

This type is the options object you pass to the useForesight hook in React and the useForesight composable in Vue.

type ForesightButtonProps = {
  registerOptions: ForesightRegisterOptionsWithoutElement
}