Block Directory: Add developer docs to readme (#25591)

ryelle · web-flow · commit 3f47cbc6d128 · 2020-09-28T10:42:26.000-04:00
diff --git a/packages/block-directory/README.md b/packages/block-directory/README.md
@@ -14,4 +14,244 @@ 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 block type to the "newly installed"
+tracking list.
+
+_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 block type from the "newly installed"
+tracking list.
+
+_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 to be displayed to the user for a given block.
+
+_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 all block 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 a block plugin install is in progress.
+
+_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>
diff --git a/packages/block-directory/src/store/actions.js b/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.
  *
@@ -150,7 +150,8 @@ export function* uninstallBlockType( block ) {
 }
 
 /**
- * Returns an action object used to add a newly installed block type.
+ * Returns an action object used to add a block type to the "newly installed"
+ * tracking list.
  *
  * @param {Object} item The block item with the block id and name.
  *
@@ -164,7 +165,8 @@ export function addInstalledBlockType( item ) {
 }
 
 /**
- * Returns an action object used to remove a newly installed block type.
+ * Returns an action object used to remove a block type from the "newly installed"
+ * tracking list.
  *
  * @param {string} item The block item with the block id and name.
  *
@@ -178,7 +180,7 @@ export function removeInstalledBlockType( item ) {
 }
 
 /**
- * Returns an action object used to indicate install in progress
+ * Returns an action object used to indicate install in progress.
  *
  * @param {string} blockId
  * @param {boolean} isInstalling
@@ -194,11 +196,11 @@ export function setIsInstalling( blockId, isInstalling ) {
 }
 
 /**
- * Sets an error notice string to be displayed to the user
+ * Sets an error notice to be displayed to the user for a given block.
  *
- * @param {string} blockId The ID of the block plugin. eg: my-block
+ * @param {string} blockId  The ID of the block plugin. eg: my-block
  * @param {string} message  The message shown in the notice.
- * @param {boolean} isFatal Whether the user can recover from the error
+ * @param {boolean} isFatal Whether the user can recover from the error.
  *
  * @return {Object} Action object.
  */
@@ -212,7 +214,7 @@ export function setErrorNotice( blockId, message, isFatal = false ) {
 }
 
 /**
- * Sets the error notice to empty for specific block
+ * Sets the error notice to empty for specific block.
  *
  * @param {string} blockId The ID of the block plugin. eg: my-block
  *
diff --git a/packages/block-directory/src/store/selectors.js b/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 (
@@ -28,12 +27,12 @@ export function isRequestingDownloadableBlocks( state, filterValue ) {
 }
 
 /**
- * Returns the available uninstalled blocks
+ * Returns the available uninstalled blocks.
  *
  * @param {Object} state       Global application state.
  * @param {string} filterValue Search string.
  *
- * @return {Array} Downloadable blocks
+ * @return {Array} Downloadable blocks.
  */
 export function getDownloadableBlocks( 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;
@@ -95,19 +95,19 @@ export const getUnusedBlockTypes = createRegistrySelector(
 );
 
 /**
- * Returns true if application is calling install endpoint.
+ * Returns true if a block plugin install is in progress.
  *
- * @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;
 }
 
 /**
- * Returns the error notices
+ * Returns all block error notices.
  *
  * @param {Object} state Global application state.
  *

Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ import getPluginUrl from './utils/get-plugin-url';`
`12`	`12`
`13`	`13`	`/**`
`14`	`14`	`* Returns an action object used in signalling that the downloadable blocks`
`15`		`- * have been requested and is loading.`
	`15`	`+ * have been requested and are loading.`
`16`	`16`	`*`
`17`	`17`	`* @param {string} filterValue Search string.`
`18`	`18`	`*`
`@@ -150,7 +150,8 @@ export function* uninstallBlockType( block ) {`
`150`	`150`	`}`
`151`	`151`
`152`	`152`	`/**`
`153`		`- * Returns an action object used to add a newly installed block type.`
	`153`	`+ * Returns an action object used to add a block type to the "newly installed"`
	`154`	`+ * tracking list.`
`154`	`155`	`*`
`155`	`156`	`* @param {Object} item The block item with the block id and name.`
`156`	`157`	`*`
`@@ -164,7 +165,8 @@ export function addInstalledBlockType( item ) {`
`164`	`165`	`}`
`165`	`166`
`166`	`167`	`/**`
`167`		`- * Returns an action object used to remove a newly installed block type.`
	`168`	`+ * Returns an action object used to remove a block type from the "newly installed"`
	`169`	`+ * tracking list.`
`168`	`170`	`*`
`169`	`171`	`* @param {string} item The block item with the block id and name.`
`170`	`172`	`*`
`@@ -178,7 +180,7 @@ export function removeInstalledBlockType( item ) {`
`178`	`180`	`}`
`179`	`181`
`180`	`182`	`/**`
`181`		`- * Returns an action object used to indicate install in progress`
	`183`	`+ * Returns an action object used to indicate install in progress.`
`182`	`184`	`*`
`183`	`185`	`* @param {string} blockId`
`184`	`186`	`* @param {boolean} isInstalling`
`@@ -194,11 +196,11 @@ export function setIsInstalling( blockId, isInstalling ) {`
`194`	`196`	`}`
`195`	`197`
`196`	`198`	`/**`
`197`		`- * Sets an error notice string to be displayed to the user`
	`199`	`+ * Sets an error notice to be displayed to the user for a given block.`
`198`	`200`	`*`
`199`		`- * @param {string} blockId The ID of the block plugin. eg: my-block`
	`201`	`+ * @param {string} blockId The ID of the block plugin. eg: my-block`
`200`	`202`	`* @param {string} message The message shown in the notice.`
`201`		`- * @param {boolean} isFatal Whether the user can recover from the error`
	`203`	`+ * @param {boolean} isFatal Whether the user can recover from the error.`
`202`	`204`	`*`
`203`	`205`	`* @return {Object} Action object.`
`204`	`206`	`*/`
`@@ -212,7 +214,7 @@ export function setErrorNotice( blockId, message, isFatal = false ) {`
`212`	`214`	`}`
`213`	`215`
`214`	`216`	`/**`
`215`		`- * Sets the error notice to empty for specific block`
	`217`	`+ * Sets the error notice to empty for specific block.`
`216`	`218`	`*`
`217`	`219`	`* @param {string} blockId The ID of the block plugin. eg: my-block`
`218`	`220`	`*`
Original file line number	Diff line number	Diff line change
`@@ -11,11 +11,10 @@ import hasBlockType from './utils/has-block-type';`
`11`	`11`	`/**`
`12`	`12`	`* Returns true if application is requesting for downloadable blocks.`
`13`	`13`	`*`
`14`		`- * @param {Object} state Global application state.`
	`14`	`+ * @param {Object} state Global application state.`
`15`	`15`	`* @param {string} filterValue Search string.`
`16`	`16`	`*`
`17`		`- *`
`18`		`- * @return {Array} Downloadable blocks`
	`17`	`+ * @return {boolean} Whether a request is in progress for the blocks list.`
`19`	`18`	`*/`
`20`	`19`	`export function isRequestingDownloadableBlocks( state, filterValue ) {`
`21`	`20`	`if (`
`@@ -28,12 +27,12 @@ export function isRequestingDownloadableBlocks( state, filterValue ) {`
`28`	`27`	`}`
`29`	`28`
`30`	`29`	`/**`
`31`		`- * Returns the available uninstalled blocks`
	`30`	`+ * Returns the available uninstalled blocks.`
`32`	`31`	`*`
`33`	`32`	`* @param {Object} state Global application state.`
`34`	`33`	`* @param {string} filterValue Search string.`
`35`	`34`	`*`
`36`		`- * @return {Array} Downloadable blocks`
	`35`	`+ * @return {Array} Downloadable blocks.`
`37`	`36`	`*/`
`38`	`37`	`export function getDownloadableBlocks( state, filterValue ) {`
`39`	`38`	`if (`
`@@ -46,11 +45,12 @@ export function getDownloadableBlocks( state, filterValue ) {`
`46`	`45`	`}`
`47`	`46`
`48`	`47`	`/**`
`49`		`- * Returns the block types that have been installed on the server.`
	`48`	`+ * Returns the block types that have been installed on the server in this`
	`49`	`+ * session.`
`50`	`50`	`*`
`51`	`51`	`* @param {Object} state Global application state.`
`52`	`52`	`*`
`53`		`- * @return {Array} Block type items.`
	`53`	`+ * @return {Array} Block type items`
`54`	`54`	`*/`
`55`	`55`	`export function getInstalledBlockTypes( state ) {`
`56`	`56`	`return state.blockManagement.installedBlockTypes;`
`@@ -95,19 +95,19 @@ export const getUnusedBlockTypes = createRegistrySelector(`
`95`	`95`	`);`
`96`	`96`
`97`	`97`	`/**`
`98`		`- * Returns true if application is calling install endpoint.`
	`98`	`+ * Returns true if a block plugin install is in progress.`
`99`	`99`	`*`
`100`		`- * @param {Object} state Global application state.`
	`100`	`+ * @param {Object} state Global application state.`
`101`	`101`	`* @param {string} blockId Id of the block.`
`102`	`102`	`*`
`103`		`- * @return {boolean} Whether its currently installing`
	`103`	`+ * @return {boolean} Whether this block is currently being installed.`
`104`	`104`	`*/`
`105`	`105`	`export function isInstalling( state, blockId ) {`
`106`	`106`	`return state.blockManagement.isInstalling[ blockId ] \|\| false;`
`107`	`107`	`}`
`108`	`108`
`109`	`109`	`/**`
`110`		`- * Returns the error notices`
	`110`	`+ * Returns all block error notices.`
`111`	`111`	`*`
`112`	`112`	`* @param {Object} state Global application state.`
`113`	`113`	`*`