From c6a62d65ea4972da638e02fa9d6ce74edbc2beb8 Mon Sep 17 00:00:00 2001
From: Mel Choyce <melchoyce@users.noreply.github.com>
Date: Wed, 12 Jun 2019 15:49:55 -0700
Subject: [PATCH] Add descriptive text and a link to embed documentation in
 embed blocks (#16101)

* Add descriptive text and a link to embed documentation in embed blocks

* Restructure placeholder to add instructions

* Update tests

* Standardize margin sizing
---
 packages/block-library/src/embed/editor.scss  |  4 +++
 .../src/embed/embed-placeholder.js            | 14 ++++++--
 .../embed/test/__snapshots__/index.js.snap    | 36 +++++++++++++++++++
 3 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/packages/block-library/src/embed/editor.scss b/packages/block-library/src/embed/editor.scss
index 507d38c256688..342b4fe1b116b 100644
--- a/packages/block-library/src/embed/editor.scss
+++ b/packages/block-library/src/embed/editor.scss
@@ -37,6 +37,10 @@
 	.components-placeholder__error {
 		word-break: break-word;
 	}
+
+	.components-placeholder__learn-more {
+		margin-top: 1em;
+	}
 }
 
 .block-library-embed__interactive-overlay {
diff --git a/packages/block-library/src/embed/embed-placeholder.js b/packages/block-library/src/embed/embed-placeholder.js
index b532d7b1a84a7..7a2a6f000a01f 100644
--- a/packages/block-library/src/embed/embed-placeholder.js
+++ b/packages/block-library/src/embed/embed-placeholder.js
@@ -2,13 +2,18 @@
  * WordPress dependencies
  */
 import { __, _x } from '@wordpress/i18n';
-import { Button, Placeholder } from '@wordpress/components';
+import { Button, Placeholder, ExternalLink } from '@wordpress/components';
 import { BlockIcon } from '@wordpress/block-editor';
 
 const EmbedPlaceholder = ( props ) => {
 	const { icon, label, value, onSubmit, onChange, cannotEmbed, fallback, tryAgain } = props;
 	return (
-		<Placeholder icon={ <BlockIcon icon={ icon } showColors /> } label={ label } className="wp-block-embed">
+		<Placeholder
+			icon={ <BlockIcon icon={ icon } showColors /> }
+			label={ label }
+			className="wp-block-embed"
+			instructions={ __( 'Paste a link to the content you want to display on your site.' ) }
+		>
 			<form onSubmit={ onSubmit }>
 				<input
 					type="url"
@@ -29,6 +34,11 @@ const EmbedPlaceholder = ( props ) => {
 					</p>
 				}
 			</form>
+			<div className="components-placeholder__learn-more">
+				<ExternalLink href={ __( 'https://wordpress.org/support/article/embeds/' ) }>
+					{ __( 'Learn more about embeds' ) }
+				</ExternalLink>
+			</div>
 		</Placeholder>
 	);
 };
diff --git a/packages/block-library/src/embed/test/__snapshots__/index.js.snap b/packages/block-library/src/embed/test/__snapshots__/index.js.snap
index 4b9c1f4de7f0e..78923aa24c5f6 100644
--- a/packages/block-library/src/embed/test/__snapshots__/index.js.snap
+++ b/packages/block-library/src/embed/test/__snapshots__/index.js.snap
@@ -27,6 +27,11 @@ exports[`core/embed block edit matches snapshot 1`] = `
     </span>
     Embed URL
   </div>
+  <div
+    class="components-placeholder__instructions"
+  >
+    Paste a link to the content you want to display on your site.
+  </div>
   <div
     class="components-placeholder__fieldset"
   >
@@ -45,6 +50,37 @@ exports[`core/embed block edit matches snapshot 1`] = `
         Embed
       </button>
     </form>
+    <div
+      class="components-placeholder__learn-more"
+    >
+      <a
+        class="components-external-link"
+        href="https://wordpress.org/support/article/embeds/"
+        rel="external noreferrer noopener"
+        target="_blank"
+      >
+        Learn more about embeds
+        <span
+          class="screen-reader-text"
+        >
+          (opens in a new tab)
+        </span>
+        <svg
+          aria-hidden="true"
+          class="dashicon dashicons-external components-external-link__icon"
+          focusable="false"
+          height="20"
+          role="img"
+          viewBox="0 0 20 20"
+          width="20"
+          xmlns="http://www.w3.org/2000/svg"
+        >
+          <path
+            d="M9 3h8v8l-2-1V6.92l-5.6 5.59-1.41-1.41L14.08 5H10zm3 12v-3l2-2v7H3V6h8L9 8H5v7h7z"
+          />
+        </svg>
+      </a>
+    </div>
   </div>
 </div>
 `;