The current paths in this repo are a bit unwieldy:

~ # cd ~/wp/packages/
~/wp/packages # ls
CONTRIBUTING.md  lerna.json    package.json       packages   scripts
~/wp/packages # cd packages/hooks/src/
~/wp/packages/packages/hooks/src # ls
createAddHook.js
createCurrentHook.js
createDidHook.js
createDoingHook.js
createHasHook.js
createRemoveHook.js
createRunHook.js
hooks.js
index.js
test

Proposal to simplify things a bit. Rename packages/ to src/ and get rid of the src/ directory inside each individual package:

- packages/hooks/src/*.js
+ src/hooks/*.js

The naming and inline documentation for hasFilter and hasAction implies that a boolean value is returned from these functions. However, the implementation reveals that the return value is a number representing the number of handlers present for the hook:

In typical usage this would be a non-concern, since a general truthiness condition would have the same result. Strict equality or otherwise relying on a boolean value would fail:

addFilter( 'hookName', 'my-handler', applyHandler );

if ( hasFilter( 'hookName' ) ) {
	// OK
}

if ( hasFilter( 'hookName' ) === true ) {
	// Not OK
}

Suggestion is to make one of the following changes:

• Update hasHook to return a boolean value
• Change the function name and inline documentation to reflect that a number is returned

Splitting this out from #42

Latest WordPress (4.9) updated the CSS rule used for screen-reader-text, see https://core.trac.wordpress.org/changeset/41622

Related: #23
Slack discussion: https://wordpress.slack.com/archives/C5UNMSU4R/p1501594355646576

The browser build was removed in #23 because the generated file was problematic and could not be used in a browser. Specifically, it still included require CommonJS statements and implicit dependencies on the Babel runtime.

An independent browser bundle may still be useful to include in the packages distributable for developers who would like to use a module independent of WordPress, and without an npm build process. You can see other libraries which support this installation process via tools like unpkg: https://github.com/reactjs/redux#installation

While it's questionable whether this should be a priority, or whether the browser build should occur in a consuming project with npm build process (like Wordpress), it may not be significant effort to reintroduce to existing build variant configurations.

In Core, did_action() returns the number of times a hook has been fired.

In @wordpress/hooks, didAction() returns the number of times a hook has been fired after a function has been attached to it.

For example, the following test:

const { doAction, addAction, didAction } = require( '@wordpress/hooks' );

function foo() {}

addAction( 'bar', 'foo', foo );

console.log( "We haven't done 'bar' yet", didAction( 'bar' ) );

doAction( 'bar' );

console.log( "Now we have", didAction( 'bar' ) );

console.log( "We haven't done 'baz' yet", didAction( 'baz' ) );

doAction( 'baz' );

console.log( "Now we have", didAction( 'baz' ) );

Produces:

We haven't done 'bar' yet 0
Now we have 1
We haven't done 'baz' yet 0
Now we have 0

However, the same code in PHP:

<?php

include_once( '../wordpress-develop/src/wp-includes/plugin.php' );

function foo() {}

add_action( 'bar', 'foo' );

echo "We haven't done 'bar' yet ", did_action( 'bar' ), "\n";

do_action( 'bar' );

echo "Now we have ", did_action( 'bar' ), "\n";

echo "We haven't done 'baz' yet ", did_action( 'baz' ), "\n";

do_action( 'baz' );

echo "Now we have ", did_action( 'baz' ), "\n";

Produces:

We haven't done 'bar' yet 0
Now we have 1
We haven't done 'baz' yet 0
Now we have 1

See #78 (comment)

Request:
getFilterPriority() and getActionPriority() take a hook name and callback name and return the priority the callback function was registered at, or false if no matching function is hooked.

Related: WordPress/gutenberg#6617

When trying to count words for a string which includes only content which would be removed by the sanitization which occurs prior to matching words (HTML tag / comments / etc removal), @wordpress/wordcount throws an error:

⇒ node          
> var wordcount = require( '@wordpress/wordcount' );
undefined
> wordcount.count( '<p></p>', 'words' );
TypeError: Cannot read property 'length' of null
    at Object.count (/Users/andrew/Documents/Code/vvv/www/editor/htdocs/wp-content/plugins/gutenberg/node_modules/@wordpress/wordcount/build/index.js:121:50)

As per the recent core JavaScript chat (https://wordpress.slack.com/archives/C5UNMSU4R/p1523366105000538) it would be worth exploring the possibility of removing the namespace parameter and instead making it an optional part of the hookName parameter, added via dot notation in the form hookName.vendor/plugin/function.

This would better match the function signature of our existing PHP filters and prevent the headache of forgetting the namespace parameter.

A Slack discussion last week raised the issue of creating CHANGELOG.md for each package.

Lerna can help with that https://github.com/lerna/lerna#--conventional-commits

$ lerna publish --conventional-commits (Can also be set in lerna.json)

When run with this flag, publish will use the Conventional Commits Specification to determine the version bump and generate CHANGELOG files for each package automatically.

Conventional Commits can be fully customized, a common implementation of this seen in widespread use thoughout GitHub is Angular implementation, prefixing commits with docs:, fix:, ci:, chore: and so on, when working with scoped packages the format takes on the package name as the scope, e.g. docs(i18n):, docs(a11y):, docs(is-shallow-equal): etc

Even though the Angular format above is quite common Conventional Commits is fully customizable and there are a numerous configurations available to be used from projects such as ESLint, Atom, jQuery to name but a few.

One of particular note is the jQuery preset where commits should look like:

Component: Short Description

Optional Long Description

Fixes #xxx
Closes gh-yyy
Ref #zzz

This matches quite closely the WordPress commit message format documented in our handbook:

Component: Brief summary.

Longer description with more details, such as a `new_hook` being introduced with the context of a `$post` and a `$screen`.

More paragraphs can be added as needed.

Props person, another.
Fixes #30000. See #20202, #105.

By mixing the scope package names with our own WordPress Conventional Commit Preset we could have our CHANGELOG.md files generated using a format common to existing WordPress processes which would be benfecial if the packages repo is to get merged into SVN.

See: #78 (comment)

The @wordpress/a11y module adds an element container to the page which acts as a target for speak text. However, its current styling will cause overflow (scroll) on the page when inserted as a sibling of #wpwrap.

https://github.com/WordPress/packages/blob/fd7fff1458f740204cc4e4ee2dfdb804a1c8c38b/packages/a11y/src/addContainer.js

Steps to reproduce:

1. With the Gutenberg plugin installed, navigate to Gutenberg > New Post in the admin dashboard
2. Open your developer tools console
3. Remove all nodes except #wpwrap and .a11y-speak-region
   • [ ...document.body.querySelectorAll( ':not( #wpwrap ):not( .a11y-speak-region )' ) ].forEach( ( node ) => node.parentNode.removeChild( node ) );

Expected: No scroll on page
Actual: Scroll on page

We should seek to either:

• Append .a11y-speak-region within #wpwrap
• Style .a11y-speak-region in such a way to not occupy any space

cc @omarreiss

I found hooks can be applyed on plain object. (Make WordPress Core)

Event can be also applyed on plain object in Node.js which can be used in browser too.
I don't understand what's different between hooks and Event in Node.js?

link: Node.js Event API

Related Slack discussion: https://wordpress.slack.com/archives/C5UNMSU4R/p1526840808000021

@wordpress/is-shallow-equal includes the following text to describe its purpose:

A function for performing a shallow comparison between two objects or arrays. Two values have shallow equality when all of their members are strictly equal to the corresponding member of the other.

It's not entirely clear by this description the behavior that should be expected by the following example:

isShallowEqual( [ { id: 1 } ], [ { id: 1 } ] );

...except when the reader understands referential inequality of two newly-defined objects.

We should clarify in the documentation...

• The difference between shallow equality and deep equality
  • References to Lodash's deep _.isEqual as an alternative
• An example where @wordpress/is-shallow-equal may return false where a deep isEqual would return true (as above)
  • And unit test?

The following is found in dom-ready/package.json:

"main": "build/index.js",
"module": "build-module/index.js",

When I install the package via npm install @wordpress/dom-ready --save, the main index.js file ends up in node_modules/@wordpress/dom-ready/src/index.json. So that means doing this in my js won't work:

import domReady from '@wordpress/dom-ready`;

...which results when using webpack to build my js:

Module not found: Error: Can't resolve '@wordpress/dom-ready'

shouldn't "main" : "build/index.js" be distributed as "main" : "src/index.js" ?