Extensibility: Plugin sidebar api

bin/build-plugin-zip.sh

@@ -99,7 +99,7 @@ zip -r gutenberg.zip \
 	blocks/library/*/*.php \
 	post-content.js \
 	$vendor_scripts \
-	{blocks,components,date,editor,element,hooks,i18n,data,utils,edit-post,viewport}/build/*.{js,map} \
+	{blocks,components,date,editor,element,hooks,i18n,data,utils,edit-post,viewport,plugins}/build/*.{js,map} \
 	{blocks,components,editor,edit-post}/build/*.css \
 	languages/gutenberg.pot \
 	languages/gutenberg-translations.php \

docs/extensibility.md

@@ -120,38 +120,60 @@ wp.hooks.addFilter(
 
 _Note:_ This filter must always be run on every page load, and not in your browser's developer tools console. Otherwise, a [block validation](https://wordpress.org/gutenberg/handbook/block-api/block-edit-save/#validation) error will occur the next time the post is edited. This is due to the fact that block validation occurs by verifying that the saved output matches what is stored in the post's content during editor initialization. So, if this filter does not exist when the editor loads, the block will be marked as invalid.
 
-## Adding a sidebar
+## Extending the editor's UI (Experimental)
 
-**Warning:** This is an experimental API, and is subject to change or even removal.
+Extending the editor's UI is done with in `registerPlugin` API, and allows you to define all your plugin's UI elements in one place.
 
-### Registering a sidebar
-
-`wp.editPost.__experimentalRegisterSidebar( name: string, settings: { title: string, render: function } )`
-
-This method takes a sidebar `name` and a `settings` object, containing a title and a render function. The name should contain a namespace prefix (Example: my-plugin/my-custom-sidebar).
+### `wp.plugins.__experimental.registerPlugin( name: string, { render: function } )`
 
+This method takes two arguments:
+1. `name`: A string identifying the plugin. Must be unique across all registered plugins.
+2. `settings`: An object containing the following data:
+   - `render`: A component containing the UI elements to be rendered. See the list below for all available UI elements.
+
 **Example**
 
-```js
-wp.editPost.__experimentalRegisterSidebar( 'my-plugin/my-custom-sidebar', {
-	render: function mySidebar() {
-		return <p>This is an example</p>;
-	},
+```jsx
+const { Fragment } = wp.element;
+const { PluginSidebar } = wp.editPost.__experimental;
+
+const Component = () => (
+    <Fragment>
+        <PluginSidebar name="first-sidebar-name" title="My Sidebar">
+            <p>Content of the first sidebar</p>
+        </PluginSidebar>
+        <PluginSidebar name="second-sidebar-name" title="My Second Sidebar">
+            <p>Content of the second sidebar</p>
+        </PluginSidebar>
+    </Fragment>
+);
+
+wp.plugins.__experimental.registerPlugin( 'plugin-names', {
+    render: Component,
 } );
 ```
 
-### Activating a sidebar
-
-`wp.editPost.__experimentalActivateSidebar( name: string )`
-
-This method takes the `name` of the sidebar you'd like to open. That sidebar should have been registered beforehand using the `registerSidebar` method.
-
-**Example**
+You can activate the sidebars using the following lines:
 
 ```js
-wp.editPost.__experimentalActivateSidebar( 'my-plugin/my-custom-sidebar' );
+wp.data.dispatch( 'core/edit-post' ).openGeneralSidebar( 'plugin-name/first-sidebar-name' );
+wp.data.dispatch( 'core/edit-post' ).openGeneralSidebar( 'plugin-name/second-sidebar-name' );
 ```
+
+### Available UI components
+
+The available UI components are found in the global variable `wp.editPost.__experimental`, and are React components.
 
-## Extending the editor's UI (Slot and Fill)
+#### PluginSidebar
 
-Coming soon.
+Renders a sidebar when activated.
+```jsx
+<PluginSidebar name="sidebar-name" title="Sidebar title">
+    <MySidebar />
+</PluginSidebar>
+```
+- Props
+  - `name`: A string identifying the sidebar. Must be unique for every sidebar registered within the scope of your plugin.
+  - `title`: Title displayed at the top of the sidebar. Must be a string.
+
+The contents you render within the `PluginSidebar` will show up as content within the sidebar.

edit-post/components/layout/index.js

@@ -19,6 +19,7 @@ import {
 } from '@wordpress/editor';
 import { withDispatch, withSelect } from '@wordpress/data';
 import { compose } from '@wordpress/element';
+import { PluginArea } from '@wordpress/plugins';
 
 /**
  * Internal dependencies
@@ -31,12 +32,13 @@ import VisualEditor from '../visual-editor';
 import EditorModeKeyboardShortcuts from '../keyboard-shortcuts';
 import MetaBoxes from '../meta-boxes';
 import { getMetaBoxContainer } from '../../utils/meta-boxes';
-import PluginsPanel from '../../components/plugins-panel/index.js';
+import PluginSidebar from '../plugin-sidebar';
 
 function Layout( {
 	mode,
 	editorSidebarOpened,
 	pluginSidebarOpened,
+	sidebarName,
 	publishSidebarOpened,
 	hasFixedToolbar,
 	closePublishSidebar,
@@ -81,8 +83,9 @@ function Layout( {
 				/>
 			) }
 			{ editorSidebarOpened && <Sidebar /> }
-			{ pluginSidebarOpened && <PluginsPanel /> }
+			{ pluginSidebarOpened && <PluginSidebar.Slot name={ sidebarName } /> }
 			<Popover.Slot />
+			<PluginArea />
 		</div>
 	);
 }
@@ -92,6 +95,7 @@ export default compose(
 		mode: select( 'core/edit-post' ).getEditorMode(),
 		editorSidebarOpened: select( 'core/edit-post' ).isEditorSidebarOpened(),
 		pluginSidebarOpened: select( 'core/edit-post' ).isPluginSidebarOpened(),
+		sidebarName: select( 'core/edit-post' ).getActiveGeneralSidebarName(),
 		publishSidebarOpened: select( 'core/edit-post' ).isPublishSidebarOpened(),
 		hasFixedToolbar: select( 'core/edit-post' ).isFeatureActive( 'fixedToolbar' ),
 		metaBoxes: select( 'core/edit-post' ).getMetaBoxes(),

edit-post/components/plugin-sidebar/index.js

@@ -0,0 +1,57 @@
+/**
+ * WordPress dependencies
+ */
+import { compose } from '@wordpress/element';
+import { Slot, Fill, withFocusReturn, withContext } from '@wordpress/components';
+import { withDispatch } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import './style.scss';
+import SidebarLayout from './sidebar-layout';
+
+/**
+ * Name of slot in which the sidebar should fill.
+ *
+ * @type {String}
+ */
+const SLOT_NAME = 'plugin-sidebar';
+
+/**
+ * Renders the plugin sidebar fill.
+ *
+ * @return {WPElement} Plugin sidebar fill.
+ */
+function PluginSidebar( { pluginName, name, title, onClose, children } ) {
+	return (
+		<Fill name={ [ SLOT_NAME, pluginName, name ].join( '/' ) }>
+			<SidebarLayout
+				title={ title }
+				onClose={ onClose } >
+				{ children }
+			</SidebarLayout>
+		</Fill>
+	);
+}
+
+PluginSidebar = compose( [
+	withDispatch( dispatch => {
+		return {
+			onClose: dispatch( 'core/edit-post' ).closeGeneralSidebar,
+		};
+	} ),
+	withFocusReturn,
+	withContext( 'pluginName' )(),
+] )( PluginSidebar );
+
+/**
+ * The plugin sidebar slot.
+ *
+ * @return {WPElement} The plugin sidebar slot.
+ */
+PluginSidebar.Slot = ( { name } ) => (
+	<Slot name={ [ SLOT_NAME, name ].join( '/' ) } />
+);
+
+export default PluginSidebar;

edit-post/components/plugin-sidebar/sidebar-error-boundary.js

@@ -0,0 +1,34 @@
+/**
+ * WordPress dependencies
+ */
+import { Component } from '@wordpress/element';
+import { __, sprintf } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import './style.scss';
+
+class SidebarErrorBoundary extends Component {
+	constructor( props ) {
+		super( props );
+		this.state = { hasError: false };
+	}
+
+	componentDidCatch() {
+		this.setState( { hasError: true } );
+	}
+
+	render() {
+		if ( this.state.hasError ) {
+			return (
+				<p className="edit-post-plugin-sidebar__sidebar-error-boundary__message">
+					{ sprintf( __( 'An error occurred rendering the plugin sidebar with id "%s".' ), this.props.pluginName ) }
+				</p>
+			);
+		}
+		return this.props.children;
+	}
+}
+
+export default SidebarErrorBoundary;