feat: setup and state

[ph-fritsche]

Problem description:

• We have a blind spot in our work around to keep track of changes between focus and blur so that we can trigger change events. See fix(keyboard): dispatch change event on blur #703
• We return a keyboardState in userEvent.keyboard that can be used to continue typing with that state (e.g. button still being pressed) but we currently don't support sharing state between our keyboard and pointer APIs like click feat: honor keyboardState in pointer events #713
• We lack support for scenarios like Press Ctrl -> Move Cursor -> Press Mouse Button -> Release Ctrl -> Release Mouse Button - See e.g. add pointerDown, pointerMove and pointerUp events for API #638
• We struggle with keeping track of displayed value and selection when it diverges from value property and selection on the element. - See e.g. fix(type): type a space into email and url input (#479) #712 (comment)

Suggested solution:

1. Add an abstract API that allows to e.g. press a mouse button without releasing it, keeps track of pointer state and will be used internally by all convenience functions like click or dblClick.

   const pointerState = user.pointer('[MouseLeft>]')
   user.pointer('[/MouseLeft]', {pointerState})

   feat: pointer API #742

2. Add a userEvent.setup API that exports all our APIs bound to a shared state.

   const user = userEvent.setup({document})
   user.keyboard('[ControlLeft>]')
   user.click(element) // dispatch pointer events with ctrlKey=true

   feat: setup #743

3. Use one abstraction to keep track of initial value, display value and selection across all our APIs.
   Our work around should be applied to the active element and be added to the capture phase of focus by userEvent.setup or any other of our APIs that is called earlier.
   See https://github.com/testing-library/user-event/blob/main/src/keyboard/shared/fireInputEvent.ts and https://github.com/testing-library/user-event/blob/main/src/utils/edit/selectionRange.ts

   feat: document state #744

[ph-fritsche]

@kentcdodds @nickmccurdy @MichaelDeBoey

[kentcdodds]

Number 1 and 2 feel like how DOM Testing Library exports the unbound queries as well as pre-bound ones on screen. For that reason I kind of like the idea of both of those.