Composite Events for React

A collection of higher-order components (HOCs) to easily create composite events in React components.

react-composite-events is stable, dependency-free, heavily-tested and well-documented.

ToC

• Installation
• Quick Usage
• What is a Composite Event?
• Benefits of Composite Events
• API Docs
• Target Environments
• Prior Art
• Contributing
• Project philosophy
• License

Installation

Install via Yarn:

yarn add react-composite-events

Install via NPM:

npm install --save react-composite-events

Quick Usage

You use composite events by wrapping a component in a higher-order component (HOC) that will provide a handler to the composite event:

// import `withMouseRest` HOC
import {withMouseRest} from 'react-composite-events'

// wrap div with `withMouseRest` HOC configured to fire event
// after 150 milliseconds. This will make a `onMouseRest-150`
// composite event prop available
const EnhancedDiv = withMouseRest(150)('div')

export default MyComponent extends PureComponent {
  _handleMouseRest() {
    console.log('mouse rested for 150 milliseconds');
  }

  render() {
    // Pass handler to `onMouseRest-150` composite event prop
    return (
      <EnhancedDiv onMouseRest-150={this._handleMouseRest.bind(this)}>
        Trigger event after mouse rests for 150 milliseconds
      </EnhancedDiv>
    )
  }
}

Imagine a navigation menu that displays on hover. You don't want the menu activated just when the user passes over the menu. You want it to activate when they've rested on the menu for a "short while" to indicate their interest. onMouseOver will trigger even if the mouse is just passing over an element, whereas the onMouseRest composite event will trigger only after the user has lingered for a bit. The "mouse rest" composite event is a better solution than a simple onMouseOver.

Check out the docs for withMouseRest() or the rest of the API Docs.

What is a Composite Event?

A "composite event" is an event for a component that is not part of its standard set of events, but is implemented in supplemental JavaScript code. It can be an event happening over time. In the case of DOM events, it can be a filter of existing DOM events.

Composite events were originally considered only in the context of DOM events. But with React Native and the proliferation of other non-DOM React environments, there are some composite events that do not assume a DOM environment (particularly the generic composite events).

A rather compelling and highly practical example is the "remain-in-state" DOM-related composite events. These allow handlers to be executed when a node remains in a specific event state for a specified amount of time (i.e. the user rests the mouse over a node for more than half a second).

Benefits of Composite Events

Composite events offer the following key benefits...

Encapsulation

Composite events allow sophisticated interactions with a component to be encapsulated into an implementation, so that the interaction can then be expressed as a single event.

Once a pattern of interaction is encapsulated into an implementation, you can then simply think of that interaction as its own event. The What is a Composite Event? section discusses the classic example of the "mouse rest" composite event, which encapsulates handling onMouseOver, onMouseMove, onMouseOut, and onMouseDown events of a DOM node, and also manages state for a timeout.

Semantically Equivalent to Real Events

Composite events are semantically equivalent to actual events on a component. These events are "injected" into a component as props by wrapping it in a higher-order component (HOC).

This means that you can use them and think about them in your React apps as if they were actual events on a component. This also means that you can add handlers for composite events along with actual component events.

Customizable Using Parameters

While a composite event itself doesn't take parameters, the HOC that creates it can accept parameters and produce different versions of the same "flavor" of composite event with slighly different behavior depending on the values supplied.

This may sound a little abstract, but what this means is that you can tune the behavior of a certain type of composite event through its parameters. Take the example of the "mouse rest" composite event. It lets you specify how long the mouse should be rested on a DOM node before the event is fired. This parameter makes this type of composite event more versatile than if it only supported one rest duration.

API Docs

The Composite Event HOCs are grouped by domain:

• Base - (advanced) the base HOC composer from which all other HOCs are built
• Generic - geneirc HOCs that create composite events intended to be environment-agnostic
• Mouse - the HOCs that create composite events around DOM mouse events
• Key - the HOCs that create composite events around DOM keyboard events

Target Environments

Libraries

• ESM - (EMCAScript modules) Everything transpiled to ES5 except for ES2015 import/export statements enabling tree shaking
• CJS - (CommonJS) Standard format for most bundling systems including Node
• AMD - (asynchronous module definition) Async format for browsers

Bundled distributions

Coming soon...

Prior Art

react-composite-events is heavily inspired by the Uize.Dom.VirtualEvent module that is a part of the open-source UIZE JavaScript Framework.

Contributing

Contributions are welcome! See Contributing Guidelines for more details.

Project philosophy

We take the stability of this utility package very seriously. react-composite-events follows the SemVer standard for versioning.

All updates must pass the CI build while maintaining 100% code coverage.

License

MIT. Copyright (c) 2017 Ben Ilegbodu.