Fix: Pasting captions without an image fails

[dmsnell]

Fixes #13527
See original work in #12315
See reduced input that produces the problem, shortened from the original.

When pasting content which includes the [caption] shortcode we assume
that the content is well-formed (that there is not only an <img /> in
there but also in the first position).

In this patch we fix the problem by removing the old code, which removed
the first Element node, and replaced it with code that removes the
first IMG node if one is found.

We're leaving other image nodes in place in case the caption contains
image nodes and we're not requiring that the IMG be the first child
of the caption shortcode in case people are wrapping the image in other
valid HTML like this...

[caption]<a href="some.link"><img src="some.image"></a>[/caption]

See the new unit tests for a more complete specification of the
intended behaviors.

PR reviewed, debugged, and created by:
-> LANNISTER MOB <-

• @codebykat
• @dmsnell
• @gwwar
• @kwight
• @mmtr
• @obenland
• @rodrigoi
• @vindl

Testing

Confirm that the new unit tests pass:

npm run test-unit packages/block-library/src/image
npm run test test/integration/blocks-raw-handling.spec.js

Also test by pasting in the input text which triggers the bug. In master it
should fail as described with the error in the console but in this
branch it should paste as expected without error and an image block
should appear.

Finally verify that no regressions occur when converting a classic block
which contains images with the [caption] shortcode. This was the goal
of #12315 when it was merged.

[gziolo]

Awesome teamwork Lannister! Thanks for fixing it with the unit test included. I'd love to see more PRs like this in the future :)

[gziolo]

Too soon. There is a failing unit test:

FAIL test/integration/blocks-raw-handling.spec.js (12.199s)
  ● rawHandler › should convert a caption shortcode with link
    expect(value).toMatchSnapshot()
    Received value does not match stored snapshot "rawHandler should convert a caption shortcode with link 1".
    - Snapshot
    + Received
      "<!-- wp:image {"id":754,"align":"none"} -->
    - <figure class="wp-block-image alignnone"><a href="http://build.wordpress-develop.test/wp-content/uploads/2011/07/100_5478.jpg"><img src="http://build.wordpress-develop.test/wp-content/uploads/2011/07/100_5478.jpg?w=604" alt="Bell on Wharf" class="wp-image-754"/></a><figcaption>Bell on wharf in San Francisco</figcaption></figure>
    + <figure class="wp-block-image alignnone"><a href="http://build.wordpress-develop.test/wp-content/uploads/2011/07/100_5478.jpg"><img src="http://build.wordpress-develop.test/wp-content/uploads/2011/07/100_5478.jpg?w=604" alt="Bell on Wharf" class="wp-image-754"/></a><figcaption><a href="http://build.wordpress-develop.test/wp-content/uploads/2011/07/100_5478.jpg"></a> Bell on wharf in San Francisco</figcaption></figure>
      <!-- /wp:image -->"
      271 | 	it( 'should convert a caption shortcode with link', () => {
      272 | 		const HTML = readFile( path.join( __dirname, 'fixtures/shortcode-caption-with-link.html' ) );
    > 273 | 		expect( serialize( rawHandler( { HTML } ) ) ).toMatchSnapshot();
          | 		                                              ^
      274 | 	} );
      275 | 
      276 | 	it( 'should convert a caption shortcode with caption', () => {
      at Object.toMatchSnapshot (test/integration/blocks-raw-handling.spec.js:273:49)

It looks like image should be removed together wit all wrapping html tags like anchor in this case.

[gwwar]

@gziolo this is ready for another look. I also added another unit test to account for the extra case.

[gziolo]

Thanks for addressing my comment. This change fixes this newly introduced side effect of improved handling 👍