feat(pointer)!: introduce pointerEventsCheck option

[ph-fritsche]

BREAKING CHANGE: skipPointerEvents has been removed.
Use pointerEventsCheck: PointerEventsCheckLevel.Never instead.

What:

Replace boolean skipPointerEvents with bit flag pointerEventsCheck.
Move pointer-events check from convenience APIs to pointer API.

Why:

The pointer-events check had been implemented on the pointer related APIs which have one target element.
Direct calls to pointer didn't implement the check as the pointer API does not necessarily have one target element. Therefore just moving or replicating the old implementation in pointer was impossible.
Just adding checks wasn't feasible as we know how expensive the check can be (especially in Jsdom).

How:

Let a "trigger" be one UI interaction that possibly leads to multiple events. E.g. releasing a mouse button which can trigger pointerup, mouseup, click ...
Move check into pointer API and call it on every "trigger" on every target element.

Add internal ApiLevel refs and reorganize the export so that multiple internal API calls from one user API call can be treated as one call.

Cache the result of the pointer-events check on the element.

Allow the user to specify how often we actually perform the check or potentially use a cached result per pointerEventsCheck option:

user-event/src/options.ts

Lines 6 to 18 in 4b6a58e

	export enum PointerEventsCheckLevel {
	/**
	* Check pointer events on every user interaction that triggers a bunch of events.
	* E.g. once for releasing a mouse button even though this triggers `pointerup`, `mouseup`, `click`, etc...
	*/
	EachTrigger = 4,
	/** Check each target once per call to pointer (related) API */
	EachApiCall = 2,
	/** Check each event target once */
	EachTarget = 1,
	/** No pointer events check */
	Never = 0,
	}

This PR includes a drive-by fix for options per main setup. These have been dropped before.

Checklist:

• Documentation
• Tests
• Ready to be merged

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 4b6a58e:

Sandbox	Source
userEvent-PR-template	Configuration

[codecov]

Codecov Report

Merging #823 (4b6a58e) into beta (b83b259) will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff            @@
##              beta      #823   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           80        81    +1     
  Lines         1679      1701   +22     
  Branches       610       611    +1     
=========================================
+ Hits          1679      1701   +22     

Impacted Files	Coverage Δ
src/clipboard/paste.ts	100.00% <ø> (ø)
src/convenience/tab.ts	100.00% <ø> (ø)
src/options.ts	100.00% <ø> (ø)
src/pointer/index.ts	100.00% <ø> (ø)
src/setup/index.ts	100.00% <ø> (ø)
src/utility/type.ts	100.00% <ø> (ø)
src/utility/upload.ts	100.00% <ø> (ø)
src/utils/pointer/firePointerEvents.ts	100.00% <ø> (ø)
src/clipboard/copy.ts	100.00% <100.00%> (ø)
src/clipboard/cut.ts	100.00% <100.00%> (ø)
... and 12 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b83b259...4b6a58e. Read the comment docs.

[ph-fritsche]

@jesperorb You implemented the previous option. What do you think about this change?

[jesperorb]

@jesperorb You implemented the previous option. What do you think about this change?

I think it is a good change. As disabling it is not the ideal solution and more granular control is good, The flag is a better solution than just a boolean. 👍🏽

As I saw in my profiling it was a combination of the click being slow but also that a click triggered a hover or some other event. Which doubled the time although the check for pointer events should be the same, the elements are the same. And this change seems to adress that so that is nice :)

That said, I didn't understand everything but I think I got the gist of it. But I can't really visualize how I would use every option of the flag practically although I understand it conceptually.

[ph-fritsche]

Thanks for the feedback.
Yeah I don't know how much each of the values will be used. (That's why I discarded to add this on the event-level for now. Might reconsider if someone actually has a use case for this.)

EachApiCall should be a fine default. If an element becomes non-interactive per pointer-events between userEvent.anyApi() calls this will throw.

EachTarget ignores that an element might change its pointer-events and keeps the value across multiple calls (and possibly tests) as long as that element still exists. This might be an acceptable optimization for most projects.

Never can be used if one knows that there can be no pointer-events style.

EachTrigger should allow to test components that change pointer-events in pointer event handlers.

[github-actions]

🎉 This PR is included in version 14.0.0-beta.7 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀