Block Editor: Remove multiline prop from Richtext doc

[t-hamano]

Closes #61580

What?

The multiline prop for RichText components is now deprecated, so I removed it from the README.

I thought about marking this prop as deprecated and keeping it, but just like when onSplit was deprecated, I removed the prop itself from the documentation.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: t-hamano <[email protected]>
Co-authored-by: ellatrix <[email protected]>
Co-authored-by: Mamaduka <[email protected]>
Co-authored-by: andreawetzel <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[Mamaduka]

I think this property is more widely used than onSpit, and based on the #47395 discussion, we still don't have a clear migration guide to the Inner Blocks.

Noting the prop as deprecated and linking to the migration guide would be an ideal solution here.

@ellatrix, what do you think?

[t-hamano]

Noting the prop as deprecated and linking to the migration guide would be an ideal solution here.

Indeed. If we want to add a migration guide, would it be better to use the Deprecation page?

[Mamaduka]

That page is for Deprecation API; we might need to find a better place :)

[ellatrix]

We do log the prop as deprecated and link to the inner blocks documentation:

gutenberg/packages/block-editor/src/components/rich-text/multiline.js

Lines 30 to 35 in 2df566c

	deprecated( 'wp.blockEditor.RichText multiline prop', {
	since: '6.1',
	version: '6.3',
	alternative: 'nested blocks (InnerBlocks)',
	link: 'https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/nested-blocks-inner-blocks/',
	} );

[t-hamano]

I think what developers would like to know is how to implement deprecation for migrating custom blocks containing RichText components with multiline prop to innerBlocks. For example, something like this function in the List block.

gutenberg/packages/block-library/src/list/utils.js

Lines 66 to 88 in 2df566c

	export function migrateToListV2( attributes ) {
	const { values, start, reversed, ordered, type, ...otherAttributes } =
	attributes;
	const list = document.createElement( ordered ? 'ol' : 'ul' );
	list.innerHTML = values;
	if ( start ) {
	list.setAttribute( 'start', start );
	}
	if ( reversed ) {
	list.setAttribute( 'reversed', true );
	}
	if ( type ) {
	list.setAttribute( 'type', type );
	}
	const [ listBlock ] = rawHandler( { HTML: list.outerHTML } );
	return [
	{ ...otherAttributes, ...listBlock.attributes },
	listBlock.innerBlocks,
	];
	}

Perhaps the Developer Blog is suitable for such implementation examples?

[Mamaduka]

@ellatrix, right, the deprecation notice links to InnerBlocks documentation, but based on the feedback, it seems that people are still struggling with migrations.

@t-hamano, a post on the developers' blog sounds good to me. cc @ndiego @ryanwelcher

[t-hamano]

a post on the developers' blog sounds good to me.

I have never written for the Developer blog, but if the migration guide is useful to many people, I would be happy to help.

By the way, I have already written code to test migrations in my personal repository: https://github.com/t-hamano/multiline-deprecation-example

• In the trunk branch, the multiline prop is applied to the RichText component.
• The v1 branch uses the InnerBlocks and also implements block migration.
• Inserting a block on the trunk branch and switching to the v1 branch will perform the block migration.

I hope this code is useful.

In any case, I would like to merge this PR.

[Mamaduka]

Sounds good. Thank you, @t-hamano!