Nicolas Gallagher
9ce8711d5a
This is a partial replacement for the 'Press' responder: 1. `useTap` is scoped to pointers (no keyboard support). Our current thinking is that "responders" should be limited to working with pointers, and that they can be combined with 'useKeyboard' in user-space. For example, we might create a 'usePress' hook in user-space that combines 'useTap' with 'useKeyboard' to react to both pointers and keyboard interactions. 2. `useTap` cancels the gesture once the pointer moves over an element that is not within the responder target's subtree. This differs from `usePress` (and React Native), where the gesture remains active after the pointer exits the target's subtree and is restarted once the pointer reenters. One of the drawbacks with the `usePress` behavior is that it requires repeatedly measuring DOM elements (which can cause jank) to perform hit region tests. `useTap` avoids doing this and relies on `document.elementFromPoint` only to support the TouchEvent fallbacks. 3. `useTap` calls `onTapUpdate` when the active gesture's state changes, `onTapEnd` when the gesture successfully completes. and `onTapCancel` when it fails. There is no `onTap` callback. `usePress` did not explicitly report back when the gesture failed, and product developers were confused about the difference between `onPress` and `onPressEnd`. 4. `useTap` explicitly separates the PointerEvent implementation from the MouseEvent/TouchEvent fallback. 5. `useTap` has better unit test coverage . All pointer types and the fallback environment are tested. The shape of the gesture state object is also defined and tested.
react-events
This package is experimental. It is intended for use with the experimental React events API that is not available in open source builds.
Event Responders attach to a host node. They listen to native browser events dispatched on the host node of their child and transform those events into high-level events for applications.
The core API is documented below. Documentation for individual Event Responders can be found here.
Event Responder Interface
An Event Responder Interface is defined using an object. Each responder can define DOM events to listen to, handle the synthetic responder events, dispatch custom events, and implement a state machine.
// types
type ResponderEventType = string;
type ResponderEvent = {|
nativeEvent: any,
target: Element | Document,
pointerType: string,
type: string,
passive: boolean,
passiveSupported: boolean,
|};
type CustomEvent = {
type: string,
target: Element,
...
}
getInitialState?: (props: null | Object) => Object
The initial state of that the Event Responder is created with.
onEvent?: (event: ResponderEvent, context: ResponderContext, props, state)
Called during the bubble phase of the targetEventTypes dispatched on DOM
elements within the Event Responder.
onMount?: (context: ResponderContext, props, state)
Called after an Event Responder in mounted.
onRootEvent?: (event: ResponderEvent, context: ResponderContext, props, state)
Called when any of the rootEventTypes are dispatched on the root of the app.
onUnmount?: (context: ResponderContext, props, state)
Called before an Event Responder in unmounted.
rootEventTypes?: Array
Defines the DOM events to listen to on the root of the app.
targetEventTypes?: Array
Defines the DOM events to listen to within the Event Responder subtree.
ResponderContext
The Event Responder Context is exposed via the context argument for certain methods
on the EventResponder object.
addRootEventTypes(eventTypes: Array)
This can be used to dynamically listen to events on the root of the app only when it is necessary to do so.
clearTimeout(id: Symbol): void
Clear a timeout defined using context.setTimeout.
dispatchEvent(propName: string, event: CustomEvent, { discrete: boolean })
Dispatches a custom synthetic event. The type and target are required
fields if the event is an object, but any other fields can be defined on the event that will be passed
to the listener. You can also pass a value that is not an object, but a boolean. For example:
const event = { type: 'press', target, pointerType, x, y };
context.dispatchEvent('onPress', event, DiscreteEvent);
isTargetWithinNode(target: Element, element: Element): boolean
Returns true if target is a child of element.
isTargetWithinResponder(target: Element): boolean
Returns true is the target element is within the subtree of the Event Responder.
isTargetWithinResponderScope(target: Element): boolean
Returns true is the target element is within the current Event Responder's scope. If the target element
is within the scope of the same responder, but owned by another Event Responder instance, this will return false.
removeRootEventTypes(eventTypes: Array)
Remove the root event types added with addRootEventTypes.
setTimeout(func: () => void, delay: number): Symbol
This can be used to dispatch async events, e.g., those that fire after a delay.