[BUG] `onHoverStart` and `onHoverEnd` types does not correspond to the actual event

[ziloen]

Describe the bug

onHoverStart and onHoverEnd typed as (event: MouseEvent, info: EventInfo): void, but the actual event is PointerEvent, and can not get event.currentTarget

IMPORTANT: Provide a CodeSandbox reproduction of the bug

stackblitz

Steps to reproduce

Steps to reproduce the behavior:

1. Open stackblitz
2. Open browser devtools - console
3. Hover the blue <div />

Expected behavior

The type is the same as the actual event, and event.currentTarget is preserved.

[gurkerl83]

Confirming this observation, type inconsistency here is one problem, but the more severe problem is that the gesture /hover feature of framer-motion schedules an (async) frame update, where the original event or at least its value for currentTarget gets lost in the process.

This also happens for other items in the "gesture" features package like "tap - PressGesture" and the "drag" feature package (things "drag" and "pan").

Lokal testing shows that avoiding a frame update at all maintains the original event. Still, there might be a reason why doing the frame update in the first place, e.g., getting motion values back, but not entirely sure if this is the reason.

https://github.com/framer/motion/blame/4f3aa5ab4ffbd3e3584ecaa5ff1b92d4c884da53/packages/framer-motion/src/gestures/hover.ts#L23

There might be a way, storing the currentTarget in a variable before the the frame.update function gets called. Create a new event object by spreading the original event and overriding currentTarget.

@mattgperry Is my observation correct or do I miss something.

[gurkerl83]

After investigating the existing implementation, I found that we were directly using the event object within the event handler. While this approach usually works, it has its limitations—specifically when trying to access event properties like currentTarget asynchronously or outside of the immediate event lifecycle.

To resolve this, I've revised the HoverGesture class to store the most recent hover event in a member variable. This adjustment enables more reliable and deferred access to the currentTarget property and mitigates issues that may arise due to JavaScript's event pooling or object recycling.

In the updated code, I've also added comments explaining when storing a simple reference to the event object is sufficient and when you might need to consider cloning the event object. This is notably relevant when we're using frame.update() to defer the execution of callbacks to the next animation frame.

Please review the modified code and let me know if it addresses the original issues effectively.

import { addPointerEvent } from "../events/add-pointer-event"
import { pipe } from "../utils/pipe"
import { isDragActive } from "./drag/utils/lock"
import type { EventInfo } from "../events/types"
import type { VisualElement } from "../render/VisualElement"
import { Feature } from "../motion/features/Feature"
import { frame } from "../frameloop"

type HoverCallback = (event: MouseEvent | null, info: EventInfo | null) => void

type HoverEventHandler = (
    event: PointerEvent,
    info: EventInfo,
    hoverCallback: HoverCallback | undefined
) => void

function addHoverEvent(
    node: VisualElement<Element>,
    isActive: boolean,
    eventHandler: HoverEventHandler
) {
    const { animationState } = node

    const eventName = isActive ? "pointerenter" : "pointerleave"

    const { onHoverStart, onHoverEnd, whileHover } = node.getProps()
    const hoverCallback = isActive ? onHoverStart : onHoverEnd

    if (animationState && whileHover) {
        animationState.setActive("whileHover", isActive)
    }

    return addPointerEvent(
        node.current!,
        eventName,
        (event, info) => {
            eventHandler(event, info, hoverCallback)
        },
        {
            passive: !hoverCallback,
        }
    )
}

export class HoverGesture extends Feature<Element> {
    private lastHoverEvent: PointerEvent | null = null
    private lastHoverEventInfo: EventInfo | null = null

    private handleEvent: HoverEventHandler = (event, info, hoverCallback) => {
        /**
         * Storing the Last Hover Event for Later Use
         *
         * When Storing the Reference is Sufficient:
         * - If you are confident that the event object will not be modified or
         *   garbage collected before you access it, storing the reference should suffice.
         *
         * When Cloning Might Be Needed:
         * - If you suspect that the event object might be volatile or subject to
         *   external changes, you might want to clone it.
         *
         *   this.lastHoverEvent = { ...event };
         */
        this.lastHoverEvent = event

        this.lastHoverEventInfo = info

        if (event.type === "touch" || isDragActive()) return

        if (hoverCallback) {
            /**
             * Using frame.update to Defer Execution
             *
             * The frame.update method schedules the callback to be executed in the
             * next animation frame. This might mean that the 'currentTarget' property
             * on the event object could be null by the time this executes, as the event object
             * might be recycled or modified.
             *
             * This is why storing 'lastHoverEvent' might be important, especially if you need
             * access to 'currentTarget' or other properties that might change.
             */
            frame.update(() =>
                hoverCallback(this.lastHoverEvent, this.lastHoverEventInfo)
            )
        }
    }

    mount() {
        this.unmount = pipe(
            addHoverEvent(this.node, true, this.handleEvent),
            addHoverEvent(this.node, false, this.handleEvent)
        ) as VoidFunction
    }

    unmount() {}
}

Thx!