Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Compose: Documentation: Document withGlobalEvents #15175

Merged
merged 1 commit into from
Apr 25, 2019
Merged

Compose: Documentation: Document withGlobalEvents #15175

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion packages/compose/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,20 @@ _Returns_

<a name="withGlobalEvents" href="#withGlobalEvents">#</a> **withGlobalEvents**

Undocumented declaration.
Higher-order component creator which, given an object of DOM event types and
values corresponding to a callback function name on the component, will
create or update a window event handler to invoke the callback when an event
occurs. On behalf of the consuming developer, the higher-order component
manages unbinding when the component unmounts, and binding at most a single
event handler for the entire application.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting. Isn't that a built in feature of addEventListener to bind once at most?

The event listener list will not contain multiple event listeners with equal type, callback, and capture, as add an event listener prevents that.

https://dom.spec.whatwg.org/#dom-eventtarget-addeventlistener

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The key words there being "equal [..] callback". Since function() {} !== function() {}, it's not reused.

Try in the console, for example:

[ ...Array( 5 ) ].forEach( ( v, i ) => document.addEventListener( 'click', () => console.log( 'click' + i ) ) )

image

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting. Isn't that a built in feature of addEventListener to bind once at most?

While it's not really relevant for change here, the question does get me wondering whether it really matters to consolidate to a single event handler. I'm trying to recall from the original implementation (#5730) whether I'd thought this was some sort of performance enhancement (i.e. one 'scroll' handler on the window rather than one for every component) and if that was the case, whether there's actually any truth to the consolidation being an optimization. I might expect a browser with its low-level language code could iterate to invoke individual callbacks of addEventListener faster than we could iterate to invoke the Listener callbacks here in JavaScript.


_Parameters_

- _eventTypesToHandlers_ `Object<string,string>`: Object with keys of DOM event type, the value a name of the function on the original component's instance which handles the event.

_Returns_

- `Function`: Higher-order component.

<a name="withInstanceId" href="#withInstanceId">#</a> **withInstanceId**

Expand Down
17 changes: 17 additions & 0 deletions packages/compose/src/with-global-events/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,23 @@ import Listener from './listener';
*/
const listener = new Listener();

/**
* Higher-order component creator which, given an object of DOM event types and
* values corresponding to a callback function name on the component, will
* create or update a window event handler to invoke the callback when an event
* occurs. On behalf of the consuming developer, the higher-order component
* manages unbinding when the component unmounts, and binding at most a single
* event handler for the entire application.
*
* @param {Object<string,string>} eventTypesToHandlers Object with keys of DOM
* event type, the value a
* name of the function on
* the original component's
* instance which handles
* the event.
*
* @return {Function} Higher-order component.
*/
function withGlobalEvents( eventTypesToHandlers ) {
return createHigherOrderComponent( ( WrappedComponent ) => {
class Wrapper extends Component {
Expand Down