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

[melchoyce]

Description

The lack of help text in the embed blocks has confused people. This PR adds some additional help text and a link to the embed docs in HelpHub.

Screenshots

Before:

After:

Fixes #8976.

[talldan]

I think you should be able to pass this text straight into the Placeholder component as a prop instead of creating a separate div:

gutenberg/packages/components/src/placeholder/index.js

Line 33 in 0cc2e02

{ !! instructions && <div className="components-placeholder__instructions">{ instructions }</div> }

Something like this would work:

<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.' ) }
>

[melchoyce]

Updated!

[talldan]

This looks good! Nice improvement.

There's a unit test failing at the moment, it's a snapshot test that checks that the html of the Embed block is correct—it'll need to be updated to reflect the changes.

Not sure if that's something you've done before @melchoyce, happy to guide you through the process if needed (it's pretty easy) or I can push a commit myself that updates the tests.

Edit: I'll just leave some info :)

There's a guide here to updating snapshot tests:
https://developer.wordpress.org/block-editor/contributors/develop/testing-overview/#tldr-broken-snapshots

It says to run npm run test-unit -- --updateSnapshot --testPathPattern path/to/tests in the terminal.

I personally do it differently (more steps but in my opinion it's a better feedback loop, and it will notify you of failed tests as you're developing):

1. Run npm run test-unit:watch in the terminal
2. Make changes to the file and save the changes, e.g. as described in this comment Add descriptive text and a link to embed documentation in embed blocks #16101 (comment)
3. The changes to the file should trigger a re-run of the tests.
4. When they've finished running there will be a prompt like 1 snapshot failed from 1 test suite. Inspect your code changes or press 'u' to update them.. If the changes look correct, press the 'u' key as it describes, and the snapshot will be updated.
5. Stage and commit the changed files (including the snapshot file).

[melchoyce]

Okay... I think that worked?

[notnownikki]

Thank you, adding links to help is something we should be doing a lot more! Will review this more tomorrow if no one else has got to it before then, but it's looking great!

[melchoyce]

Thanks Nikki!! Let me know if there's any other blocks offhand you think need some links 😄

[kjellr]

This looks excellent, thanks for the change, Mel. The tests are passing, so it looks like the snapshots are all set. 👍

I shared on super-minor comment about the learn more margin. Once that's updated, this should be good to merge.