Packages: Add new @wordpress/data-controls package.

bin/update-readmes.js

@@ -17,6 +17,7 @@ const packages = [
 		'Autogenerated selectors': 'src/selectors.js',
 	} ],
 	'data',
+	'data-controls',
 	'date',
 	'deprecated',
 	'dom',

docs/manifest-devhub.json

@@ -1079,6 +1079,12 @@
 		"markdown_source": "../packages/custom-templated-path-webpack-plugin/README.md",
 		"parent": "packages"
 	},
+	{
+		"title": "@wordpress/data-controls",
+		"slug": "packages-data-controls",
+		"markdown_source": "../packages/data-controls/README.md",
+		"parent": "packages"
+	},
 	{
 		"title": "@wordpress/data",
 		"slug": "packages-data",

docs/manifest.json

@@ -287,6 +287,12 @@
 		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/custom-templated-path-webpack-plugin/README.md",
 		"parent": "packages"
 	},
+	{
+		"title": "@wordpress/data-controls",
+		"slug": "packages-data-controls",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/data-controls/README.md",
+		"parent": "packages"
+	},
 	{
 		"title": "@wordpress/data",
 		"slug": "packages-data",

package.json

@@ -28,6 +28,7 @@
 		"@wordpress/compose": "file:packages/compose",
 		"@wordpress/core-data": "file:packages/core-data",
 		"@wordpress/data": "file:packages/data",
+		"@wordpress/data-controls": "file:packages/data-controls",
 		"@wordpress/date": "file:packages/date",
 		"@wordpress/deprecated": "file:packages/deprecated",
 		"@wordpress/dom": "file:packages/dom",

packages/data-controls/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Master
+
+Initial release of the @wordpress/data-controls package.

packages/data-controls/README.md

@@ -0,0 +1,136 @@
+# Data Controls
+
+The data controls module is a module intended to simplify implementation of common controls used with the [`@wordpress/data`](/packages/data/README.md) package.
+
+**Note:** It is assumed that the registry being used has the controls plugin enabled on it (see [more details on controls here](https://github.com/WordPress/gutenberg/tree/master/packages/data#controls))
+
+## Installation
+
+Install the module
+
+```bash
+npm install @wordpress/data-controls --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)._
+
+The following controls are available on the object returned by the module:
+
+## API
+
+<!-- START TOKEN(Autogenerated API docs) -->
+
+<a name="apiFetch" href="#apiFetch">#</a> **apiFetch**
+
+Dispatches a control action for triggering an api fetch call.
+
+_Usage_
+
+```js
+import { apiFetch } from '@wordpress/data-controls';
+
+// Action generator using apiFetch
+export function* myAction {
+	const path = '/v2/my-api/items';
+	const items = yield apiFetch( { path } );
+	// do something with the items.
+}
+```
+
+_Parameters_
+
+-   _request_ `Object`: Arguments for the fetch request.
+
+_Returns_
+
+-   `Object`: The control descriptor.
+
+<a name="controls" href="#controls">#</a> **controls**
+
+The default export is what you use to register the controls with your custom
+store.
+
+_Usage_
+
+```js
+// WordPress dependencies
+import { controls } from '@wordpress/data-controls';
+import { registerStore } from '@wordpress/data';
+
+// Internal dependencies
+import reducer from './reducer';
+import * as selectors from './selectors';
+import * as actions from './actions';
+import * as resolvers from './resolvers';
+
+registerStore ( 'my-custom-store', {
+	reducer,
+	controls,
+	actions,
+	selectors,
+	resolvers,
+} );
+```
+
+_Returns_
+
+-   `Object`: An object for registering the default controls with the store.
+
+<a name="dispatch" href="#dispatch">#</a> **dispatch**
+
+Dispatches a control action for triggering a registry dispatch.
+
+_Usage_
+
+```js
+import { dispatch } from '@wordpress/data-controls';
+
+// Action generator using dispatch
+export function* myAction {
+  yield dispatch( 'core/edit-post' ).togglePublishSidebar();
+  // do some other things.
+}
+```
+
+_Parameters_
+
+-   _storeKey_ `string`: The key for the store the action belongs to
+-   _actionName_ `string`: The name of the action to dispatch
+-   _args_ `Array`: Arguments for the dispatch action.
+
+_Returns_
+
+-   `Object`: The control descriptor.
+
+<a name="select" href="#select">#</a> **select**
+
+Dispatches a control action for triggering a registry select.
+
+Note: when this control action is handled, it automatically considers
+selectors that may have a resolver. It will await and return the resolved
+value when the selector has not been resolved yet.
+
+_Usage_
+
+```js
+import { select } from '@wordpress/data-controls';
+
+// Action generator using select
+export function* myAction {
+	const isSidebarOpened = yield select( 'core/edit-post', 'isEditorSideBarOpened' );
+	// do stuff with the result from the select.
+}
+```
+
+_Parameters_
+
+-   _storeKey_ `string`: The key for the store the selector belongs to
+-   _selectorName_ `string`: The name of the selector
+-   _args_ `Array`: Arguments for the select.
+
+_Returns_
+
+-   `Object`: The control descriptor.
+
+
+<!-- END TOKEN(Autogenerated API docs) -->

packages/data-controls/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "@wordpress/data-controls",
+	"version": "1.0.0-beta.1",
+	"description": "A set of common controls for the @wordpress/data api.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"data",
+		"controls"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/master/packages/data-controls/README.md",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git",
+		"directory": "packages/data-controls"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"main": "build/index.js",
+	"module": "build-module/index.js",
+	"react-native": "src/index",
+	"dependencies": {
+		"@wordpress/api-fetch": "file:../api-fetch",
+		"@wordpress/data": "file:../data"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}