From f4e401b50639d2a22d35c295bdae1fb1debe8af7 Mon Sep 17 00:00:00 2001
From: Piotr Delawski <piotr.delawski@gmail.com>
Date: Tue, 18 May 2021 22:36:52 +0200
Subject: [PATCH] Update slotfills docs

---
 .../slotfills/plugin-preview-menu-item.md     | 46 +++++++++++-----
 .../developers/slotfills/plugin-preview.md    | 52 ++++++++++++-------
 2 files changed, 68 insertions(+), 30 deletions(-)

diff --git a/docs/designers-developers/developers/slotfills/plugin-preview-menu-item.md b/docs/designers-developers/developers/slotfills/plugin-preview-menu-item.md
index 8ff1e899114a8e..fc40135cf9c9a7 100644
--- a/docs/designers-developers/developers/slotfills/plugin-preview-menu-item.md
+++ b/docs/designers-developers/developers/slotfills/plugin-preview-menu-item.md
@@ -1,34 +1,56 @@
 # PluginPreviewMenuItem
 
-This is designed to be used alongside the PluginPreview.
+Adds a menu item to the "Preview" menu.
 
--   PluginPreviewMenuItem: Adds a menu item to the "Preview" menu.
--   PluginPreview: Renders the main content area when that menu item is chosen.
+It is designed to be used alongside the `PluginPreview` that renders a custom preview instead of the `VisualEditor` in the block editor.
 
-Each of these takes 2 props, `previewId`, and `children`.
+The presence of the `PluginPreview` component is not necessary.
+Selecting a preview will not replace the `VisualEditor` with a custom preview in such a case.
+Instead, a plugin author may rely on the `onClick` event handler entirely.
 
--   `previewId` - A string that serves as an internal identifier for your
-    preview. Must match across PluginPreviewMenuItem and PluginPreview.
--   `children` - What gets rendered in that spot.
+## Available Props
+
+-   **previewId** `string`: A string identifying the preview. When used, must match across `PluginPreviewMenuItem` and `PluginPreview`.
+-   **icon** `(string|Element)`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element.
+-   **onClick** `Function`: Click handler, e.g. for previews that do not register slot fills.
 
 ## Example
 
 ```js
 import { registerPlugin } from '@wordpress/plugins';
 import { PluginPreview, PluginPreviewMenuItem } from '@wordpress/block-editor';
-import { Fragment } from '@wordpress/element';
+import { external } from '@wordpress/icons';
 
 const PluginPreviewTest = () => (
-	<Fragment>
+	<>
 		<PluginPreviewMenuItem previewId="preview-custom-1">
-			Custom Preview 1 Menu Text
+			Custom preview 1
 		</PluginPreviewMenuItem>
 		<PluginPreview previewId="preview-custom-1">
 			<div>
-				<h4>Custom Preview 1 Content</h4>
+				<h1>Custom Preview 1 Content</h1>
+			</div>
+		</PluginPreview>
+
+		<PluginPreviewMenuItem
+			previewId="preview-custom-2"
+			onClick={ ( event ) => console.log( event ) }
+		>
+			Custom preview 2
+		</PluginPreviewMenuItem>
+		<PluginPreview previewId="preview-custom-2">
+			<div>
+				<h1>Custom Preview 2 Content</h1>
 			</div>
 		</PluginPreview>
-	</Fragment>
+
+		<PluginPreviewMenuItem
+			icon={ external }
+			onClick={ ( event ) => console.log( event ) }
+		>
+			Custom action (no preview)
+		</PluginPreviewMenuItem>
+	</>
 );
 
 registerPlugin( 'plugin-preview-test', {
diff --git a/docs/designers-developers/developers/slotfills/plugin-preview.md b/docs/designers-developers/developers/slotfills/plugin-preview.md
index 021df443584c15..f51ca83ceca5fe 100644
--- a/docs/designers-developers/developers/slotfills/plugin-preview.md
+++ b/docs/designers-developers/developers/slotfills/plugin-preview.md
@@ -1,34 +1,50 @@
 # PluginPreview
 
-This is designed to be used alongside the PluginPreviewMenuItem.
+Renders the main content area when that menu item is chosen.
 
--   PluginPreviewMenuItem: Adds a menu item to the "Preview" menu.
--   PluginPreview: Renders the main content area when that menu item is chosen.
+It is designed to be used alongside the `PluginPreviewMenuItem` that adds a custom menu item to the "Preview" menu.
 
-Each of these takes 2 props, `previewId`, and `children`.
+## Available Props
 
--   `previewId` - A string that serves as an internal identifier for your
-    preview. Must match across PluginPreviewMenuItem and PluginPreview.
--   `children` - What gets rendered in that spot.
+-   **previewId** `string`: A string identifying the preview. Must match across `PluginPreviewMenuItem` and `PluginPreview`.
 
 ## Example
 
 ```js
 import { registerPlugin } from '@wordpress/plugins';
 import { PluginPreview, PluginPreviewMenuItem } from '@wordpress/block-editor';
-import { Fragment } from '@wordpress/element';
+import { external } from '@wordpress/icons';
 
 const PluginPreviewTest = () => (
-	<Fragment>
-		<PluginPreviewMenuItem previewId="preview-custom-1">
-			Custom Preview 1 Menu Text
-		</PluginPreviewMenuItem>
-		<PluginPreview previewId="preview-custom-1">
-			<div>
-				<h4>Custom Preview 1 Content</h4>
-			</div>
-		</PluginPreview>
-	</Fragment>
+		<>
+			<PluginPreviewMenuItem previewId="preview-custom-1">
+				Custom preview 1
+			</PluginPreviewMenuItem>
+			<PluginPreview previewId="preview-custom-1">
+				<div>
+					<h1>Custom Preview 1 Content</h1>
+				</div>
+			</PluginPreview>
+
+			<PluginPreviewMenuItem
+					previewId="preview-custom-2"
+					onClick={ ( event ) => console.log( event ) }
+			>
+				Custom preview 2
+			</PluginPreviewMenuItem>
+			<PluginPreview previewId="preview-custom-2">
+				<div>
+					<h1>Custom Preview 2 Content</h1>
+				</div>
+			</PluginPreview>
+
+			<PluginPreviewMenuItem
+					icon={ external }
+					onClick={ ( event ) => console.log( event ) }
+			>
+				Custom action (no preview)
+			</PluginPreviewMenuItem>
+		</>
 );
 
 registerPlugin( 'plugin-preview-test', {