Merge pull request #62 from studiopress/add/choices-description

Display the help text in the TextareaArray setting

.gitignore

@@ -106,6 +106,7 @@ node_modules
 vendor
 
 # Tests
+artifacts/
 tests/data/
 tests/includes/
 coverage/

gulpfile.js

@@ -68,6 +68,7 @@ gulp.task( 'wporg:trunk', function() {
 gulp.task( 'clean:bundle', function() {
 	return del( [
 		'package/trunk/package',
+		'package/trunk/artifacts',
 		'package/trunk/assets/wporg',
 		'package/trunk/coverage',
 		'package/trunk/js/src',

js/src/block-editor/components/repeater-rows.js

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import * as React from 'react';
+
 /**
  * WordPress dependencies
  */
@@ -135,10 +140,8 @@ class RepeaterRows extends Component {
 			const attribute = attr[ parentName ];
 			const repeaterRows = this.getRows( attribute );
 
-			/*
-			 * Calling slice() essentially creates a copy of repeaterRows.
-			 * Without this, it looks like setAttributes() doesn't recognize a change to the array, and the component doesn't re-render.
-			 */
+			// Calling slice() essentially creates a copy of repeaterRows.
+			// Without this, it looks like setAttributes() doesn't recognize a change to the array, and the component doesn't re-render.
 			const rows = repeaterRows.slice();
 			[ rows[ from ], rows[ to ] ] = [ rows[ to ], rows[ from ] ];
 

js/src/edit-block/components/editor-preview.js

@@ -0,0 +1,62 @@
+/**
+ * External dependencies
+ */
+import * as React from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import { useBlock, useField } from '../hooks';
+import { Fields } from '../../block-editor/components';
+
+/**
+ * The editor preview.
+ *
+ * @return {React.ReactElement} The editor preview.
+ */
+const EditorPreview = () => {
+	const { block, changeBlock } = useBlock();
+	const { getFields } = useField();
+	const { previewAttributes = {} } = block;
+	const fields = getFields();
+
+	/** @param {Object} newAttributes Attribute (field) names and values. */
+	const setAttributes = ( newAttributes ) => {
+		changeBlock( {
+			previewAttributes: {
+				...previewAttributes,
+				...newAttributes,
+			},
+		} );
+	};
+
+	return (
+		<div className="block-form">
+			{
+				Boolean( Object.keys( fields ).length )
+					? (
+						<Fields
+							key="example-fields"
+							fields={ fields }
+							parentBlockProps={ {
+								setAttributes,
+								attributes: previewAttributes,
+							} }
+							parentBlock={ {} }
+						/>
+					) : (
+						<p>
+							{ __( 'Please add a field to preview the block.', 'genesis-custom-blocks' ) }
+						</p>
+					)
+			}
+		</div>
+	);
+};
+
+export default EditorPreview;

js/src/edit-block/components/editor.js

@@ -13,17 +13,18 @@ import {
 	UnsavedChangesWarning,
 } from '@wordpress/editor';
 import { StrictMode, useState } from '@wordpress/element';
-import ServerSideRender from '@wordpress/server-side-render';
 
 /**
  * Internal dependencies
  */
 import {
 	BlockPanel,
 	BrowserURL,
+	EditorPreview,
 	EditorProvider,
 	FieldPanel,
 	FieldsGrid,
+	FrontEndPreview,
 	Header,
 	LocationButtons,
 	Main,
@@ -39,8 +40,7 @@ import {
 	TEMPLATE_EDITOR_EDITING_MODE,
 } from '../constants';
 import { DEFAULT_LOCATION } from '../../common/constants';
-import { useBlock, useField, useTemplate } from '../hooks';
-import { Fields } from '../../block-editor/components';
+import { useBlock, useTemplate } from '../hooks';
 
 /**
  * @callback onErrorType Handler for errors.
@@ -83,17 +83,25 @@ import { Fields } from '../../block-editor/components';
  * @property {string} [width] The width, like '25'.
  */
 
+/**
+ * @typedef {Object} Setting A field setting.
+ * @see PHP class Genesis\CustomBlocks\Blocks\Controls\ControlSetting
+ * @property {string} name The name of the setting.
+ * @property {string} label The label of the setting to display in the GCB editor.
+ * @property {string} help A help value that display in the GCB editor.
+ * @property {string} type The setting type, like 'width' or 'text', not a data type like boolean.
+ * @property {*} default The default value.
+ */
+
 /**
  * The editor component.
  *
  * @param {EditorProps} props The component props.
  * @return {React.ReactElement} The editor.
  */
 const Editor = ( { onError, postId, postType, settings } ) => {
-	const { block, changeBlock } = useBlock();
+	const { block } = useBlock();
 	const { template } = useTemplate();
-	const { previewAttributes = {} } = block;
-	const { getFields } = useField();
 	const post = useSelect(
 		( select ) => select( 'core' ).getEntityRecord( 'postType', postType, postId ),
 		[ postId, postType ]
@@ -104,16 +112,6 @@ const Editor = ( { onError, postId, postType, settings } ) => {
 	const [ panelDisplaying, setPanelDisplaying ] = useState( BLOCK_PANEL );
 	const [ selectedField, setSelectedField ] = useState( NO_FIELD_SELECTED );
 
-	/** @param {Object} newAttributes Attribute (field) name and value. */
-	const setAttributes = ( newAttributes ) => {
-		changeBlock( {
-			previewAttributes: {
-				...previewAttributes,
-				...newAttributes,
-			},
-		} );
-	};
-
 	if ( ! post ) {
 		return null;
 	}
@@ -139,19 +137,8 @@ const Editor = ( { onError, postId, postType, settings } ) => {
 									setCurrentLocation={ setCurrentLocation }
 								/>
 								{ EDITOR_PREVIEW_EDITING_MODE === editorMode && block && block.fields
-									? (
-										<div className="block-form">
-											<Fields
-												key="example-fields"
-												fields={ getFields() }
-												parentBlockProps={ {
-													setAttributes,
-													attributes: previewAttributes,
-												} }
-												parentBlock={ {} }
-											/>
-										</div>
-									) : null
+									? <EditorPreview />
+									: null
 								}
 								{ BUILDER_EDITING_MODE === editorMode
 									? (
@@ -165,14 +152,8 @@ const Editor = ( { onError, postId, postType, settings } ) => {
 									) : null
 								}
 								{ FRONT_END_PREVIEW_EDITING_MODE === editorMode
-									? (
-										<ServerSideRender
-											block={ `genesis-custom-blocks/${ block.name }` }
-											attributes={ previewAttributes }
-											className="genesis-custom-blocks-editor__ssr"
-											httpMethod="POST"
-										/>
-									) : null
+									? <FrontEndPreview />
+									: null
 								}
 								{ TEMPLATE_EDITOR_EDITING_MODE === editorMode
 									? <TemplateEditor />

js/src/edit-block/components/front-end-preview.js

@@ -0,0 +1,72 @@
+/**
+ * External dependencies
+ */
+import * as React from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useSelect } from '@wordpress/data';
+import { PostSavedState } from '@wordpress/editor';
+import { __ } from '@wordpress/i18n';
+import ServerSideRender from '@wordpress/server-side-render';
+
+/**
+ * Internal dependencies
+ */
+import { getBlock, getBlockNameWithNameSpace } from '../helpers';
+
+/**
+ * The front-end preview of the block.
+ *
+ * Gets the saved post with .getCurrentPost(),
+ * not the edited post.
+ * The server side only has access to the saved post.
+ * So there can be an error in <ServerSideRender>
+ * if it passes attributes that aren't yet saved.
+ *
+ * @return {React.ReactElement} The front-end preview.
+ */
+const FrontEndPreview = () => {
+	const currentPost = useSelect( ( select ) => select( 'core/editor' ).getCurrentPost() );
+	const isPostNew = useSelect( ( select ) => select( 'core/editor' ).isEditedPostNew() );
+	const isPostDirty = useSelect( ( select ) => select( 'core/editor' ).isEditedPostDirty() );
+
+	const fullBlock = getBlock( currentPost?.content );
+	const blockNameWithNameSpace = getBlockNameWithNameSpace( fullBlock );
+	const block = fullBlock[ blockNameWithNameSpace ] || {};
+
+	// There's nothing entered or saved, so <ServerSideRender> would have an error.
+	if ( isPostNew && ! isPostDirty ) {
+		return (
+			<p className="mt-4">
+				{ __( 'Please edit the block to preview it.', 'genesis-custom-blocks' ) }
+			</p>
+		);
+	}
+
+	return (
+		<>
+			{
+				isPostNew && isPostDirty
+					? (
+						<div className="mt-4 flex flex-row items-center">
+							{ __( 'Please save your block to preview it:', 'genesis-custom-blocks' ) }
+							&nbsp;
+							<PostSavedState />
+						</div>
+					)
+					: (
+						<ServerSideRender
+							block={ `genesis-custom-blocks/${ block?.name }` }
+							attributes={ block?.previewAttributes }
+							className="genesis-custom-blocks-editor__ssr"
+							httpMethod="POST"
+						/>
+					)
+			}
+		</>
+	);
+};
+
+export default FrontEndPreview;

js/src/edit-block/components/header.js

@@ -109,10 +109,7 @@ const Header = ( { editorMode, setEditorMode } ) => {
 			</button>
 			<div id="save-and-publish">
 				<span className="mr-3 text-sm">
-					<PostSavedState
-						forceIsDirty={ false }
-						forceIsSaving={ false }
-					/>
+					<PostSavedState	/>
 				</span>
 				<span className="mr-3">
 					<PostPublishButton />

js/src/edit-block/components/index.js

@@ -4,11 +4,13 @@ export { default as BrowserURL } from './browser-url';
 export { default as CategorySection } from './category-section';
 export { default as ClipboardCopy } from './clipboard-copy';
 export { default as Editor } from './editor';
+export { default as EditorPreview } from './editor-preview';
 export { default as EditorProvider } from './editor-provider';
 export { default as Field } from './field';
 export { default as FieldPanel } from './field-panel';
 export { default as FieldsGrid } from './fields-grid';
 export { default as FieldSettings } from './field-settings';
+export { default as FrontEndPreview } from './front-end-preview';
 export { default as Header } from './header';
 export { default as IconSection } from './icon-section';
 export { default as Input } from './input';

js/src/edit-block/components/input.js

@@ -6,7 +6,7 @@ import * as React from 'react';
 /**
  * @typedef {Object} InputProps The component props.
  * @property {Function} handleOnChange Handles a change in this setting.
- * @property {Object} setting This setting.
+ * @property {import('./editor').Setting} setting This setting.
  * @property {string} type The type of <input>, like 'text'.
  * @property {string|undefined} value The setting value.
  * @property {number} [min] The min attribute of an input[type="number"].

js/src/edit-block/components/select.js

@@ -8,7 +8,7 @@ import * as React from 'react';
  * @property {Function} handleOnChange Handles a change in this setting.
  * @property {string} id The id attribute.
  * @property {Array} options The options, including their label and value.
- * @property {Object} setting This setting.
+ * @property {import('./editor').Setting} setting This setting.
  * @property {string|undefined} value The setting value.
  */
 

js/src/edit-block/components/settings/checkbox.js

@@ -6,8 +6,8 @@ import * as React from 'react';
 /**
  * @typedef {Object} CheckboxProps The component props.
  * @property {Function} handleOnChange Handles a change in this setting.
- * @property {Object} setting This setting.
- * @property {boolean|number|undefined} value The setting value.
+ * @property {import('../editor').Setting} setting This setting.
+ * @property {boolean|undefined} value The setting value.
  */
 
 /**

js/src/edit-block/components/settings/email.js

@@ -10,7 +10,7 @@ import { Input } from '../';
 
 /**
  * @typedef {Object} EmailProps The component props.
- * @property {Object} setting This setting.
+ * @property {import('../editor').Setting} setting This setting.
  * @property {string|undefined} value The setting value.
  * @property {Function} handleOnChange Handles a change in this setting.
  */

js/src/edit-block/components/settings/index.js

@@ -7,4 +7,5 @@ export { default as NumberNonNegative } from './number-non-negative';
 export { default as Text } from './text';
 export { default as Textarea } from './textarea';
 export { default as TextareaArray } from './textarea-array';
+export { default as TextareaDefault } from './textarea-default';
 export { default as Width } from './width';

js/src/edit-block/components/settings/location.js

@@ -11,7 +11,7 @@ import { LOCATIONS_WITH_LABEL, LOCATIONS } from '../../../common/constants';
 
 /**
  * @typedef {Object} LocationProps The component props.
- * @property {Object} setting This setting.
+ * @property {import('../editor').Setting} setting This setting.
  * @property {string|undefined} value The setting value.
  * @property {Function} handleOnChange Handles a change to this setting.
  * @property {Function} setCurrentLocation Sets the selected location, like 'editor'.

js/src/edit-block/components/settings/new-line-format.js

@@ -15,7 +15,7 @@ import { Select } from '../';
 
 /**
  * @typedef {Object} NewLineFormatProps The component props.
- * @property {Object} setting This setting.
+ * @property {import('../editor').Setting} setting This setting.
  * @property {string|undefined} value The setting value.
  * @property {Function} handleOnChange Handles a change to this setting.
  */

js/src/edit-block/components/settings/number-non-negative.js

@@ -10,7 +10,7 @@ import { Input } from '../';
 
 /**
  * @typedef {Object} NumberNonNegativeProps The component props.
- * @property {Object} setting This setting.
+ * @property {import('../editor').Setting} setting This setting.
  * @property {string|undefined} value The setting value.
  * @property {Function} handleOnChange Handles a change in this setting.
  */

js/src/edit-block/components/settings/number.js

@@ -10,7 +10,7 @@ import { Input } from '../';
 
 /**
  * @typedef {Object} NumberProps The component props.
- * @property {Object} setting This setting.
+ * @property {import('../editor').Setting} setting This setting.
  * @property {string|undefined} value The setting value.
  * @property {Function} handleOnChange Handles a change in this setting.
  */