PluginPreview{MenuItem,}: Change external interface "deviceName" -> "…

…previewId"

docs/designers-developers/developers/slotfills/plugin-preview-menu-item.md

@@ -5,9 +5,9 @@ This is designed to be used alongside the PluginPreview.
 -   PluginPreviewMenuItem: Adds a menu item to the "Preview" menu.
 -   PluginPreview: Renders the main content area when that menu item is chosen.
 
-Each of these takes 2 props, `deviceName`, and `children`.
+Each of these takes 2 props, `previewId`, and `children`.
 
--   `deviceName` - A string that serves as an internal identifier for your
+-   `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.
 
@@ -20,10 +20,10 @@ import { Fragment } from '@wordpress/element';
 
 const PluginPreviewTest = () => (
 	<Fragment>
-		<PluginPreviewMenuItem deviceName="preview-custom-1">
+		<PluginPreviewMenuItem previewId="preview-custom-1">
 			Custom Preview 1 Menu Text
 		</PluginPreviewMenuItem>
-		<PluginPreview deviceName="preview-custom-1">
+		<PluginPreview previewId="preview-custom-1">
 			<div>
 				<h4>Custom Preview 1 Content</h4>
 			</div>

docs/designers-developers/developers/slotfills/plugin-preview.md

@@ -5,9 +5,9 @@ This is designed to be used alongside the PluginPreviewMenuItem.
 -   PluginPreviewMenuItem: Adds a menu item to the "Preview" menu.
 -   PluginPreview: Renders the main content area when that menu item is chosen.
 
-Each of these takes 2 props, `deviceName`, and `children`.
+Each of these takes 2 props, `previewId`, and `children`.
 
--   `deviceName` - A string that serves as an internal identifier for your
+-   `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.
 
@@ -20,10 +20,10 @@ import { Fragment } from '@wordpress/element';
 
 const PluginPreviewTest = () => (
 	<Fragment>
-		<PluginPreviewMenuItem deviceName="preview-custom-1">
+		<PluginPreviewMenuItem previewId="preview-custom-1">
 			Custom Preview 1 Menu Text
 		</PluginPreviewMenuItem>
-		<PluginPreview deviceName="preview-custom-1">
+		<PluginPreview previewId="preview-custom-1">
 			<div>
 				<h4>Custom Preview 1 Content</h4>
 			</div>

packages/block-editor/README.md

@@ -240,15 +240,7 @@ Undocumented declaration.
 
 <a name="coreDeviceTypes" href="#coreDeviceTypes">#</a> **coreDeviceTypes**
 
-This is an array of strings. The strings returned represent deviceType values
-that belong to the core system. When the deviceType, returned by
-`__experimentalGetPreviewDeviceType()`, is one of these values, the built in
-VisualEditor is responsible for rendering a preview of that type.
-
-When the deviceType is something other than one of the coreDeviceTypes, we are
-rendering a custom deviceType registered by the <PluginPreviewMenuItem /> and
-<PluginPreview /> components, and defer to a <Slot /> filled by the plugin to
-draw the preview.
+Undocumented declaration.
 
 <a name="createCustomColorsHOC" href="#createCustomColorsHOC">#</a> **createCustomColorsHOC**
 
@@ -461,26 +453,26 @@ _Related_
 
 <a name="PluginPreview" href="#PluginPreview">#</a> **PluginPreview**
 
-React Component; Used by a plugin to define the contents of a "custom
+Component used by a plugin to define the contents of a "custom
 preview". The children of this component will be displayed in the main editor
 screen when this "custom preview" is chosen from the preview menu.
 
 _Parameters_
 
 -   _props_ `Object`: Component properties.
--   _props.deviceName_ `string`: The internal name of this custom preview. Must
-    match the _deviceName_ given to `PluginPreviewMenuItem`.
+-   _props.previewId_ `string`: The internal name of this custom preview. Must match the _previewId_ given to `PluginPreviewMenuItem`.
 -   _props.children_ `WPElement`: Children to be rendered.
 
 <a name="PluginPreviewMenuItem" href="#PluginPreviewMenuItem">#</a> **PluginPreviewMenuItem**
 
-React Component; Used by a plugin to define the contents of a menu item that
+Component used by a plugin to define the contents of a menu item that
 selects a "custom preview". The children of this component will be displayed
 inside the preview menu. Typically a single string is good enough.
 
+_Parameters_
+
 -   _props_ `Object`: Component properties.
--   _props.deviceName_ `string`: The internal name of this custom preview. Must
-    match the _deviceName_ given to `PluginPreview`.
+-   _props.previewId_ `string`: The internal name of this custom preview. Must match the _previewId_ given to `PluginPreview`.
 -   _props.children_ `WPElement`: Children to be rendered.
 
 <a name="PreserveScrollInReorder" href="#PreserveScrollInReorder">#</a> **PreserveScrollInReorder**

packages/block-editor/src/components/preview-options/index.js

@@ -11,6 +11,18 @@ import { DropdownMenu, MenuGroup, MenuItem, Slot } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 import { check } from '@wordpress/icons';
 
+/*
+ * coreDeviceTypes: An array of strings. The strings returned represent
+ * deviceType values that belong to the core system. When the deviceType,
+ * returned by `__experimentalGetPreviewDeviceType()`, is one of these values,
+ * the built in VisualEditor is responsible for rendering a preview of that
+ * type.
+
+ * When the deviceType is something other than one of the coreDeviceTypes, we are
+ * rendering a custom deviceType registered by the <PluginPreviewMenuItem /> and
+ * <PluginPreview /> components, and defer to a <Slot /> filled by the plugin to
+ * draw the preview.
+ */
 export const coreDeviceTypes = [ 'Desktop', 'Tablet', 'Mobile' ];
 
 export default function PreviewOptions( {

packages/block-editor/src/components/preview-options/plugin-preview-menu-item/index.js

@@ -10,9 +10,18 @@ import { check } from '@wordpress/icons';
  */
 import { coreDeviceTypes } from '../index';
 
+/**
+ * Component used by a plugin to define the contents of a menu item that
+ * selects a "custom preview". The children of this component will be displayed
+ * inside the preview menu. Typically a single string is good enough.
+ *
+ * @param {Object} props          Component properties.
+ * @param {string} props.previewId The internal name of this custom preview. Must match the _previewId_ given to `PluginPreview`.
+ * @param {WPElement} props.children Children to be rendered.
+ */
 export default function PluginPreviewMenuItem( {
 	children,
-	deviceName,
+	previewId,
 	...props
 } ) {
 	const {
@@ -28,15 +37,15 @@ export default function PluginPreviewMenuItem( {
 		[]
 	);
 
-	if ( coreDeviceTypes.includes( deviceName ) ) {
+	if ( coreDeviceTypes.includes( previewId ) ) {
 		return null;
 	}
 
 	return (
 		<Fill name="core/block-editor/plugin-preview-menu" { ...props }>
 			<MenuItem
-				onClick={ () => setPreviewDeviceType( deviceName ) }
-				icon={ deviceType === deviceName && check }
+				onClick={ () => setPreviewDeviceType( previewId ) }
+				icon={ deviceType === previewId && check }
 			>
 				{ children }
 			</MenuItem>

packages/block-editor/src/components/preview-options/plugin-preview/index.js

@@ -3,10 +3,19 @@
  */
 import { Fill } from '@wordpress/components';
 
-export default function PluginPreview( { children, deviceName, ...props } ) {
+/**
+ * Component used by a plugin to define the contents of a "custom
+ * preview". The children of this component will be displayed in the main editor
+ * screen when this "custom preview" is chosen from the preview menu.
+ *
+ * @param {Object} props          Component properties.
+ * @param {string} props.previewId The internal name of this custom preview. Must match the _previewId_ given to `PluginPreviewMenuItem`.
+ * @param {WPElement} props.children Children to be rendered.
+ */
+export default function PluginPreview( { children, previewId, ...props } ) {
 	return (
 		<Fill
-			name={ 'core/block-editor/plugin-preview/' + deviceName }
+			name={ 'core/block-editor/plugin-preview/' + previewId }
 			{ ...props }
 		>
 			{ children }