/** * Copyright (c) Nicolas Gallagher * Copyright (c) Facebook, Inc. and its affiliates. * * This source code is licensed under the MIT license found in the * LICENSE file in the root directory of this source tree. * * @flow */ /** * RESPONDER EVENT SYSTEM * * A single, global "interaction lock" on views. For a view to be the "responder" means * that pointer interactions are exclusive to that view and none other. The "interaction * lock" can be transferred (only) to ancestors of the current "responder" as long as * pointers continue to be active. * * Responder being granted: * * A view can become the "responder" after the following events: * * "pointerdown" (implemented using "touchstart", "mousedown") * * "pointermove" (implemented using "touchmove", "mousemove") * * "scroll" (while a pointer is down) * * "select" (while a pointer is down) * * If nothing is already the "responder", the event propagates to (capture) and from * (bubble) the event target until a view returns `true` for * `on*ShouldSetResponder(Capture)`. * * If something is already the responder, the event propagates to (capture) and from * (bubble) the lowest common ancestor of the event target and the current "responder". * Then negotiation happens between the current "responder" and a view that wants to * become the "responder": see the timing diagram below. * * (NOTE: Scrolled views either automatically become the "responder" or release the * "interaction lock". A native scroll view that isn't built on top of the responder * system must result in the current "responder" being notified that it no longer has * the "interaction lock" - the native system has taken over. * * Responder being released: * * As soon as there are no more active pointers that *started* inside descendants * of the *current* "responder", an `onResponderRelease` event is dispatched to the * current "responder", and the responder lock is released. * * Typical sequence of events: * * startShouldSetResponder * * responderGrant/Reject * * responderStart * * responderMove * * responderEnd * * responderRelease */ /* Negotiation Performed +-----------------------+ / \ Process low level events to + Current Responder + wantsResponderID determine who to perform negot-| (if any exists at all) | iation/transition | Otherwise just pass through| -------------------------------+----------------------------+------------------+ Bubble to find first ID | | to return true:wantsResponderID| | | | +--------------+ | | | onTouchStart | | | +------+-------+ none | | | return| | +-----------v-------------+true| +------------------------+ | |onStartShouldSetResponder|----->| onResponderStart (cur) |<-----------+ +-----------+-------------+ | +------------------------+ | | | | | +--------+-------+ | returned true for| false:REJECT +-------->|onResponderReject | wantsResponderID | | | +----------------+ | (now attempt | +------------------+-----+ | | handoff) | | onResponder | | +------------------->| TerminationRequest | | | +------------------+-----+ | | | | +----------------+ | true:GRANT +-------->|onResponderGrant| | | +--------+-------+ | +------------------------+ | | | | onResponderTerminate |<-----------+ | +------------------+-----+ | | | | +----------------+ | +-------->|onResponderStart| | | +----------------+ Bubble to find first ID | | to return true:wantsResponderID| | | | +-------------+ | | | onTouchMove | | | +------+------+ none | | | return| | +-----------v-------------+true| +------------------------+ | |onMoveShouldSetResponder |----->| onResponderMove (cur) |<-----------+ +-----------+-------------+ | +------------------------+ | | | | | +--------+-------+ | returned true for| false:REJECT +-------->|onResponderReject | wantsResponderID | | | +----------------+ | (now attempt | +------------------+-----+ | | handoff) | | onResponder | | +------------------->| TerminationRequest| | | +------------------+-----+ | | | | +----------------+ | true:GRANT +-------->|onResponderGrant| | | +--------+-------+ | +------------------------+ | | | | onResponderTerminate |<-----------+ | +------------------+-----+ | | | | +----------------+ | +-------->|onResponderMove | | | +----------------+ | | | | Some active touch started| | inside current responder | +------------------------+ | +------------------------->| onResponderEnd | | | | +------------------------+ | +---+---------+ | | | onTouchEnd | | | +---+---------+ | | | | +------------------------+ | +------------------------->| onResponderEnd | | No active touches started| +-----------+------------+ | inside current responder | | | | v | | +------------------------+ | | | onResponderRelease | | | +------------------------+ | | | + + */ import type { ResponderEvent } from './createResponderEvent'; import type { TouchActionValue } from '../../__types__/styles'; import { addEvent } from '#internal/addEvent'; import createResponderEvent from './createResponderEvent'; import { getActiveModality } from '#internal/modality'; import supportsDOM from '#internal/supportsDOM'; import { isCancelish, isEndish, isMoveish, isScroll, isSelect, isStartish } from './ResponderEventTypes'; import { getLowestCommonAncestor, getResponderEventPath, getResponderConfig, hasTargetTouches, isPrimaryPointerDown, setResponderConfig } from './utils'; import ResponderTouchHistoryStore from './ResponderTouchHistoryStore'; /* ------------ TYPES ------------ */ type ActiveResponderInstance = { responderEventPath: Array, node: HTMLElement, }; type EmptyResponderInstance = { responderEventPath: null, node: null, }; type ResponderInstance = ActiveResponderInstance | EmptyResponderInstance; export type ResponderConfig = {| // Direct responder events dispatched directly to responder. Do not bubble. onResponderEnd?: ?(e: ResponderEvent) => void, onResponderGrant?: ?(e: ResponderEvent) => void, onResponderMove?: ?(e: ResponderEvent) => void, onResponderRelease?: ?(e: ResponderEvent) => void, onResponderReject?: ?(e: ResponderEvent) => void, onResponderStart?: ?(e: ResponderEvent) => void, onResponderTerminate?: ?(e: ResponderEvent) => void, onResponderTerminationRequest?: ?(e: ResponderEvent) => boolean, // On pointer down, should this element become the responder? onStartShouldSetResponder?: ?(e: ResponderEvent) => boolean, onStartShouldSetResponderCapture?: ?(e: ResponderEvent) => boolean, // On pointer move, should this element become the responder? onMoveShouldSetResponder?: ?(e: ResponderEvent) => boolean, onMoveShouldSetResponderCapture?: ?(e: ResponderEvent) => boolean, // On scroll, should this element become the responder? Do no bubble onScrollShouldSetResponder?: ?(e: ResponderEvent) => boolean, onScrollShouldSetResponderCapture?: ?(e: ResponderEvent) => boolean, // On select, should this element become the responder? onSelectShouldSetResponder?: ?(e: ResponderEvent) => boolean, onSelectShouldSetResponderCapture?: ?(e: ResponderEvent) => boolean, touchAction?: TouchActionValue, |}; /* ------------ IMPLEMENTATION ------------ */ const startRegistration = ['onStartShouldSetResponderCapture', 'onStartShouldSetResponder', { bubbles: true }]; const moveRegistration = ['onMoveShouldSetResponderCapture', 'onMoveShouldSetResponder', { bubbles: true }]; const scrollRegistration = ['onScrollShouldSetResponderCapture', 'onScrollShouldSetResponder', { bubbles: false }]; const shouldSetResponderEvents = { touchstart: startRegistration, mousedown: startRegistration, touchmove: moveRegistration, mousemove: moveRegistration, scroll: scrollRegistration }; const emptyResponder = { responderEventPath: null, node: null }; let trackedTouchCount = 0; let currentResponder: ResponderInstance = { node: null, responderEventPath: null }; declare function changeCurrentResponder(responder: ResponderInstance): any; /** * Process native events * * A single event listener is used to manage the responder system. * All pointers are tracked in the ResponderTouchHistoryStore. Native events * are interpreted in terms of the Responder System and checked to see if * the responder should be transferred. Each host node that is attached to * the Responder System has an ID, which is used to look up its associated * callbacks. */ declare function eventListener(domEvent: any): any; /** * Walk the event path to/from the target node. At each node, stop and call the * relevant "shouldSet" functions for the given event type. If any of those functions * call "stopPropagation" on the event, stop searching for a responder. */ declare function findWantsResponder(domEvent: any, responderEvent: any, responderEventPath: any): any; /** * Attempt to transfer the responder. */ declare function attemptTransfer(responderEvent: ResponderEvent, wantsResponder: ActiveResponderInstance): any; /* ------------ PUBLIC API ------------ */ /** * Attach Listeners * * Use native events as ReactDOM doesn't have a non-plugin API to implement * this system. */ declare export function attachListeners(): any; /** * Register a config with node attached to the ResponderSystem. */ declare export function setConfig(node: EventTarget, config: ?ResponderConfig): any; /** * Allow the current responder to be terminated from within components to support * more complex requirements, such as use with other React libraries for working * with scroll views, input views, etc. */ declare export function terminateResponder(): any; /** * Allow unit tests to inspect the current responder in the system. * FOR TESTING ONLY. */ declare export function getResponderNode(): ?HTMLElement; const ResponderSystem = { attachListeners, setConfig, terminateResponder, getResponderNode }; export default ResponderSystem;