Skip to content

Commit

Permalink
React events: add delay props to Press module (#15340)
Browse files Browse the repository at this point in the history
* Add delay props to Press event module
* Minor naming changes to Hover events
* Add examples to react-events README
  • Loading branch information
necolas authored Apr 6, 2019
1 parent 4064ea9 commit 81a61b1
Show file tree
Hide file tree
Showing 5 changed files with 537 additions and 132 deletions.
157 changes: 117 additions & 40 deletions packages/react-events/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,31 @@
*This package is experimental. It is intended for use with the experimental React
events API that is not available in open source builds.*

Event components do not render 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.


## Focus

The `Focus` module responds to focus and blur events on the element it wraps.
Focus events are dispatched for `mouse`, `pen`, `touch`, and `keyboard`
pointer types.

```js
// Example
const TextField = (props) => (
<Focus
onBlur={props.onBlur}
onFocus={props.onFocus}
>
<textarea></textarea>
</Focus>
);
```

```js
// Types
type FocusEvent = {}
```

Expand Down Expand Up @@ -38,69 +55,124 @@ The `Hover` module responds to hover events on the element it wraps. Hover
events are only dispatched for `mouse` pointer types. Hover begins when the
pointer enters the element's bounds and ends when the pointer leaves.

```js
// Example
const Link = (props) => (
const [ hovered, setHovered ] = useState(false);
return (
<Hover onHoverChange={setHovered}>
<a
{...props}
href={props.href}
style={{
...props.style,
textDecoration: hovered ? 'underline': 'none'
}}
/>
</Hover>
);
);
```

```js
// Types
type HoverEvent = {}
```

### disabled: boolean
### delayHoverEnd: number

Disables all `Hover` events.
The duration of the delay between when hover ends and when `onHoverEnd` is
called.

### onHoverStart: (e: HoverEvent) => void
### delayHoverStart: number

Called once the element is hovered. It will not be called if the pointer leaves
the element before the `delayHoverStart` threshold is exceeded. And it will not
be called more than once before `onHoverEnd` is called.
The duration of the delay between when hover starts and when `onHoverStart` is
called.

### onHoverEnd: (e: HoverEvent) => void
### disabled: boolean

Called once the element is no longer hovered. It will be cancelled if the
pointer leaves the element before the `delayHoverStart` threshold is exceeded.
Disables all `Hover` events.

### onHoverChange: boolean => void

Called when the element changes hover state (i.e., after `onHoverStart` and
`onHoverEnd`).

### delayHoverStart: number
### onHoverEnd: (e: HoverEvent) => void

The duration of the delay between when hover starts and when `onHoverStart` is
called.
Called once the element is no longer hovered. It will be cancelled if the
pointer leaves the element before the `delayHoverStart` threshold is exceeded.

### delayHoverEnd: number
### onHoverStart: (e: HoverEvent) => void

The duration of the delay between when hover ends and when `onHoverEnd` is
called.
Called once the element is hovered. It will not be called if the pointer leaves
the element before the `delayHoverStart` threshold is exceeded. And it will not
be called more than once before `onHoverEnd` is called.


## Press

The `Press` module responds to press events on the element it wraps. Press
events are dispatched for `mouse`, `pen`, `touch`, and `keyboard` pointer types.

Press events are only dispatched for keyboards when pressing the Enter or
Spacebar keys. If neither `onPress` nor `onLongPress` are called, this signifies
that the press ended outside of the element hit bounds (i.e., the user aborted
the press).

```js
// Example
const Button = (props) => (
const [ pressed, setPressed ] = useState(false);
return (
<Press
onPress={props.onPress}
onPressChange={setPressed}
onLongPress={props.onLongPress}
>
<div
{...props}
role="button"
tabIndex={0}
style={
...buttonStyles,
...(pressed && pressedStyles)
}}
/>
</Press>
);
);
```

```js
// Types
type PressEvent = {}

type PressOffset = {
top: number,
right: number,
bottom: number,
right: number
};
```

### disabled: boolean
### delayLongPress: number = 500ms

Disables all `Press` events.
The duration of a press before `onLongPress` and `onLongPressChange` are called.

### onPressStart: (e: PressEvent) => void
### delayPressEnd: number

Called once the element is pressed down. If the press is released before the
`delayPressStart` threshold is exceeded then the delay is cut short and
`onPressStart` is called immediately.
The duration of the delay between when the press ends and when `onPressEnd` is
called.

### onPressEnd: (e: PressEvent) => void
### delayPressStart: number

Called once the element is no longer pressed. It will be cancelled if the press
starts again before the `delayPressEnd` threshold is exceeded.
The duration of a delay between when the press starts and when `onPressStart` is
called. This delay is cut short (and `onPressStart` is called) if the press is
released before the threshold is exceeded.

### onPressChange: boolean => void
### disabled: boolean

Called when the element changes press state (i.e., after `onPressStart` and
`onPressEnd`).
Disables all `Press` events.

### onLongPress: (e: PressEvent) => void

Expand All @@ -117,25 +189,30 @@ Determines whether calling `onPress` should be cancelled if `onLongPress` or

### onPress: (e: PressEvent) => void

Called after `onPressEnd` only if `onLongPressShouldCancelPress` returns
`false`.
Called immediately after a press is released, unless either 1) the press is
released outside the hit bounds of the element (accounting for
`pressRetentionOffset` and `TouchHitTarget`), or 2) the press was a long press,
and `onLongPress` or `onLongPressChange` props are provided, and
`onLongPressCancelsPress()` is `true`.

### delayPressStart: number
### onPressChange: boolean => void

The duration of a delay between when the press starts and when `onPressStart` is
called. This delay is cut short if the press ends released before the threshold
is exceeded.
Called when the element changes press state (i.e., after `onPressStart` and
`onPressEnd`).

### delayPressEnd: number
### onPressEnd: (e: PressEvent) => void

The duration of the delay between when the press ends and when `onPressEnd` is
called.
Called once the element is no longer pressed. If the press starts again before
the `delayPressEnd` threshold is exceeded then the delay is reset to prevent
`onPressEnd` being called during a press.

### delayLongPress: number = 500ms
### onPressStart: (e: PressEvent) => void

The duration of a press before `onLongPress` and `onLongPressChange` are called.
Called once the element is pressed down. If the press is released before the
`delayPressStart` threshold is exceeded then the delay is cut short and
`onPressStart` is called immediately.

### pressRententionOffset: { top: number, right: number, bottom: number, right: number }
### pressRententionOffset: PressOffset

Defines how far the pointer (while held down) may move outside the bounds of the
element before it is deactivated. Once deactivated, the pointer (still held
Expand Down
36 changes: 22 additions & 14 deletions packages/react-events/src/Hover.js
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ type HoverEvent = {|
type: HoverEventType,
|};

// const DEFAULT_HOVER_END_DELAY_MS = 0;
// const DEFAULT_HOVER_START_DELAY_MS = 0;
const DEFAULT_HOVER_END_DELAY_MS = 0;
const DEFAULT_HOVER_START_DELAY_MS = 0;

const targetEventTypes = [
'pointerover',
Expand Down Expand Up @@ -98,7 +98,7 @@ function dispatchHoverStartEvents(
state.hoverEndTimeout = null;
}

const dispatch = () => {
const activate = () => {
state.isActiveHovered = true;

if (props.onHoverStart) {
Expand All @@ -115,14 +115,18 @@ function dispatchHoverStartEvents(
};

if (!state.isActiveHovered) {
const delay = calculateDelayMS(props.delayHoverStart, 0, 0);
if (delay > 0) {
const delayHoverStart = calculateDelayMS(
props.delayHoverStart,
0,
DEFAULT_HOVER_START_DELAY_MS,
);
if (delayHoverStart > 0) {
state.hoverStartTimeout = context.setTimeout(() => {
state.hoverStartTimeout = null;
dispatch();
}, delay);
activate();
}, delayHoverStart);
} else {
dispatch();
activate();
}
}
}
Expand All @@ -145,7 +149,7 @@ function dispatchHoverEndEvents(
state.hoverStartTimeout = null;
}

const dispatch = () => {
const deactivate = () => {
state.isActiveHovered = false;

if (props.onHoverEnd) {
Expand All @@ -162,13 +166,17 @@ function dispatchHoverEndEvents(
};

if (state.isActiveHovered) {
const delay = calculateDelayMS(props.delayHoverEnd, 0, 0);
if (delay > 0) {
const delayHoverEnd = calculateDelayMS(
props.delayHoverEnd,
0,
DEFAULT_HOVER_END_DELAY_MS,
);
if (delayHoverEnd > 0) {
state.hoverEndTimeout = context.setTimeout(() => {
dispatch();
}, delay);
deactivate();
}, delayHoverEnd);
} else {
dispatch();
deactivate();
}
}
}
Expand Down
Loading

0 comments on commit 81a61b1

Please sign in to comment.