Block Directory: Add developer docs to readme

packages/block-directory/README.md

@@ -14,4 +14,242 @@ npm install @wordpress/block-directory --save
 
 _This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats)._
 
+## Usage
+
+This package builds a standalone JS file. When loaded on a page with the block editor, it extends the block inserter to search for blocks from WordPress.org.
+
+To do this, it uses the `__experimentalInserterMenuExtension`, a slot-fill area hooked into the block types list. When the user runs a search and there are no results currently installed, it fires off a request to WordPress.org for matching blocks. These are listed for the user to install with a one-click process that [installs, activates, and injects the block into the post.](./src/store/actions.js#L49) When the post is saved, if the block was not used, it will be [silently uninstalled](./src/store/actions.js#L129) to avoid clutter.
+
+See also the API endpoints for searching WordPress.org: `/wp/v2/block-directory/search`, and installing & activating plugins: `/wp/v2/plugins/`.
+
+## Actions
+
+The following set of dispatching action creators are available on the object returned by `wp.data.dispatch( 'core/block-directory' )`:
+
+<!-- START TOKEN(Autogenerated actions|src/store/actions.js) -->
+
+<a name="addInstalledBlockType" href="#addInstalledBlockType">#</a> **addInstalledBlockType**
+
+Returns an action object used to add a newly installed block type.
+
+_Parameters_
+
+-   _item_ `Object`: The block item with the block id and name.
+
+_Returns_
+
+-   `Object`: Action object.
+
+<a name="clearErrorNotice" href="#clearErrorNotice">#</a> **clearErrorNotice**
+
+Sets the error notice to empty for specific block
+
+_Parameters_
+
+-   _blockId_ `string`: The ID of the block plugin. eg: my-block
+
+_Returns_
+
+-   `Object`: Action object.
+
+<a name="fetchDownloadableBlocks" href="#fetchDownloadableBlocks">#</a> **fetchDownloadableBlocks**
+
+Returns an action object used in signalling that the downloadable blocks
+have been requested and are loading.
+
+_Parameters_
+
+-   _filterValue_ `string`: Search string.
+
+_Returns_
+
+-   `Object`: Action object.
+
+<a name="installBlockType" href="#installBlockType">#</a> **installBlockType**
+
+Action triggered to install a block plugin.
+
+_Parameters_
+
+-   _block_ `Object`: The block item returned by search.
+
+_Returns_
+
+-   `boolean`: Whether the block was successfully installed & loaded.
+
+<a name="receiveDownloadableBlocks" href="#receiveDownloadableBlocks">#</a> **receiveDownloadableBlocks**
+
+Returns an action object used in signalling that the downloadable blocks
+have been updated.
+
+_Parameters_
+
+-   _downloadableBlocks_ `Array`: Downloadable blocks.
+-   _filterValue_ `string`: Search string.
+
+_Returns_
+
+-   `Object`: Action object.
+
+<a name="removeInstalledBlockType" href="#removeInstalledBlockType">#</a> **removeInstalledBlockType**
+
+Returns an action object used to remove a newly installed block type.
+
+_Parameters_
+
+-   _item_ `string`: The block item with the block id and name.
+
+_Returns_
+
+-   `Object`: Action object.
+
+<a name="setErrorNotice" href="#setErrorNotice">#</a> **setErrorNotice**
+
+Sets an error notice string to be displayed to the user
+
+_Parameters_
+
+-   _blockId_ `string`: The ID of the block plugin. eg: my-block
+-   _message_ `string`: The message shown in the notice.
+-   _isFatal_ `boolean`: Whether the user can recover from the error
+
+_Returns_
+
+-   `Object`: Action object.
+
+<a name="setIsInstalling" href="#setIsInstalling">#</a> **setIsInstalling**
+
+Returns an action object used to indicate install in progress
+
+_Parameters_
+
+-   _blockId_ `string`: 
+-   _isInstalling_ `boolean`: 
+
+_Returns_
+
+-   `Object`: Action object.
+
+<a name="uninstallBlockType" href="#uninstallBlockType">#</a> **uninstallBlockType**
+
+Action triggered to uninstall a block plugin.
+
+_Parameters_
+
+-   _block_ `Object`: The blockType object.
+
+<!-- END TOKEN(Autogenerated actions|src/store/actions.js) -->
+
+## Selectors
+
+The following selectors are available on the object returned by `wp.data.select( 'core/block-directory' )`:
+
+<!-- START TOKEN(Autogenerated selectors|src/store/selectors.js) -->
+
+<a name="getDownloadableBlocks" href="#getDownloadableBlocks">#</a> **getDownloadableBlocks**
+
+Returns the available uninstalled blocks
+
+_Parameters_
+
+-   _state_ `Object`: Global application state.
+-   _filterValue_ `string`: Search string.
+
+_Returns_
+
+-   `Array`: Downloadable blocks
+
+<a name="getErrorNoticeForBlock" href="#getErrorNoticeForBlock">#</a> **getErrorNoticeForBlock**
+
+Returns the error notice for a given block.
+
+_Parameters_
+
+-   _state_ `Object`: Global application state.
+-   _blockId_ `string`: The ID of the block plugin. eg: my-block
+
+_Returns_
+
+-   `(string|boolean)`: The error text, or false if no error.
+
+<a name="getErrorNotices" href="#getErrorNotices">#</a> **getErrorNotices**
+
+Returns the error notices
+
+_Parameters_
+
+-   _state_ `Object`: Global application state.
+
+_Returns_
+
+-   `Object`: Object with error notices.
+
+<a name="getInstalledBlockTypes" href="#getInstalledBlockTypes">#</a> **getInstalledBlockTypes**
+
+Returns the block types that have been installed on the server in this
+session.
+
+_Parameters_
+
+-   _state_ `Object`: Global application state.
+
+_Returns_
+
+-   `Array`: Block type items
+
+<a name="getNewBlockTypes" href="#getNewBlockTypes">#</a> **getNewBlockTypes**
+
+Returns block types that have been installed on the server and used in the
+current post.
+
+_Parameters_
+
+-   _state_ `Object`: Global application state.
+
+_Returns_
+
+-   `Array`: Block type items.
+
+<a name="getUnusedBlockTypes" href="#getUnusedBlockTypes">#</a> **getUnusedBlockTypes**
+
+Returns the block types that have been installed on the server but are not
+used in the current post.
+
+_Parameters_
+
+-   _state_ `Object`: Global application state.
+
+_Returns_
+
+-   `Array`: Block type items.
+
+<a name="isInstalling" href="#isInstalling">#</a> **isInstalling**
+
+Returns true if application is calling install endpoint.
+
+_Parameters_
+
+-   _state_ `Object`: Global application state.
+-   _blockId_ `string`: Id of the block.
+
+_Returns_
+
+-   `boolean`: Whether this block is currently being installed.
+
+<a name="isRequestingDownloadableBlocks" href="#isRequestingDownloadableBlocks">#</a> **isRequestingDownloadableBlocks**
+
+Returns true if application is requesting for downloadable blocks.
+
+_Parameters_
+
+-   _state_ `Object`: Global application state.
+-   _filterValue_ `string`: Search string.
+
+_Returns_
+
+-   `boolean`: Whether a request is in progress for the blocks list.
+
+
+<!-- END TOKEN(Autogenerated selectors|src/store/selectors.js) -->
+
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/block-directory/src/store/actions.js

@@ -12,7 +12,7 @@ import getPluginUrl from './utils/get-plugin-url';
 
 /**
  * Returns an action object used in signalling that the downloadable blocks
- * have been requested and is loading.
+ * have been requested and are loading.
  *
  * @param {string} filterValue Search string.
  *

packages/block-directory/src/store/selectors.js

@@ -11,11 +11,10 @@ import hasBlockType from './utils/has-block-type';
 /**
  * Returns true if application is requesting for downloadable blocks.
  *
- * @param {Object} state Global application state.
+ * @param {Object} state       Global application state.
  * @param {string} filterValue Search string.
  *
- *
- * @return {Array} Downloadable blocks
+ * @return {boolean} Whether a request is in progress for the blocks list.
  */
 export function isRequestingDownloadableBlocks( state, filterValue ) {
 	if (
@@ -46,11 +45,12 @@ export function getDownloadableBlocks( state, filterValue ) {
 }
 
 /**
- * Returns the block types that have been installed on the server.
+ * Returns the block types that have been installed on the server in this
+ * session.
  *
  * @param {Object} state Global application state.
  *
- * @return {Array} Block type items.
+ * @return {Array} Block type items
  */
 export function getInstalledBlockTypes( state ) {
 	return state.blockManagement.installedBlockTypes;
@@ -97,10 +97,10 @@ export const getUnusedBlockTypes = createRegistrySelector(
 /**
  * Returns true if application is calling install endpoint.
  *
- * @param {Object} state Global application state.
+ * @param {Object} state   Global application state.
  * @param {string} blockId Id of the block.
  *
- * @return {boolean} Whether its currently installing
+ * @return {boolean} Whether this block is currently being installed.
  */
 export function isInstalling( state, blockId ) {
 	return state.blockManagement.isInstalling[ blockId ] || false;