RichText: Revise onSplit prop

docs/designers-developers/developers/data/data-core-editor.md

@@ -1578,6 +1578,7 @@ one or more replacement blocks.
 
  * clientIds: Block client ID(s) to replace.
  * blocks: Replacement block(s).
+ * index: Block index to select.
 
 ### replaceBlock
 

packages/block-library/src/heading/edit.js

@@ -16,7 +16,6 @@ export default function HeadingEdit( {
 	attributes,
 	setAttributes,
 	mergeBlocks,
-	insertBlocksAfter,
 	onReplace,
 	className,
 } ) {
@@ -48,17 +47,17 @@ export default function HeadingEdit( {
 				value={ content }
 				onChange={ ( value ) => setAttributes( { content: value } ) }
 				onMerge={ mergeBlocks }
-				unstableOnSplit={
-					insertBlocksAfter ?
-						( before, after, ...blocks ) => {
-							setAttributes( { content: before } );
-							insertBlocksAfter( [
-								...blocks,
-								createBlock( 'core/paragraph', { content: after } ),
-							] );
-						} :
-						undefined
-				}
+				onSplit={ ( value ) => {
+					if ( ! value ) {
+						return createBlock( 'core/paragraph' );
+					}
+
+					return createBlock( 'core/heading', {
+						...attributes,
+						content: value,
+					} );
+				} }
+				onReplace={ onReplace }
 				onRemove={ () => onReplace( [] ) }
 				style={ { textAlign: align } }
 				className={ className }

packages/block-library/src/list/index.js

@@ -214,7 +214,6 @@ export const settings = {
 
 	edit( {
 		attributes,
-		insertBlocksAfter,
 		setAttributes,
 		mergeBlocks,
 		onReplace,
@@ -233,25 +232,9 @@ export const settings = {
 				className={ className }
 				placeholder={ __( 'Write list…' ) }
 				onMerge={ mergeBlocks }
-				unstableOnSplit={
-					insertBlocksAfter ?
-						( before, after, ...blocks ) => {
-							if ( ! blocks.length ) {
-								blocks.push( createBlock( 'core/paragraph' ) );
-							}
-
-							if ( after !== '<li></li>' ) {
-								blocks.push( createBlock( 'core/list', {
-									ordered,
-									values: after,
-								} ) );
-							}
-
-							setAttributes( { values: before } );
-							insertBlocksAfter( blocks );
-						} :
-						undefined
-				}
+				onSplit={ ( value ) => createBlock( name, { values: value } ) }
+				onSplitMiddle={ () => createBlock( 'core/paragraph' ) }
+				onReplace={ onReplace }
 				onRemove={ () => onReplace( [] ) }
 				onTagNameChange={ ( tag ) => setAttributes( { ordered: tag === 'ol' } ) }
 			/>

packages/block-library/src/paragraph/edit.js

@@ -54,10 +54,9 @@ class ParagraphBlock extends Component {
 
 		this.onReplace = this.onReplace.bind( this );
 		this.toggleDropCap = this.toggleDropCap.bind( this );
-		this.splitBlock = this.splitBlock.bind( this );
 	}
 
-	onReplace( blocks ) {
+	onReplace( blocks, indexToSelect ) {
 		const { attributes, onReplace } = this.props;
 		onReplace( blocks.map( ( block, index ) => (
 			index === 0 && block.name === name ?
@@ -68,7 +67,7 @@ class ParagraphBlock extends Component {
 					},
 				} :
 				block
-		) ) );
+		) ), indexToSelect );
 	}
 
 	toggleDropCap() {
@@ -80,49 +79,6 @@ class ParagraphBlock extends Component {
 		return checked ? __( 'Showing large initial letter.' ) : __( 'Toggle to show a large initial letter.' );
 	}
 
-	/**
-	 * Split handler for RichText value, namely when content is pasted or the
-	 * user presses the Enter key.
-	 *
-	 * @param {?Array}     before Optional before value, to be used as content
-	 *                            in place of what exists currently for the
-	 *                            block. If undefined, the block is deleted.
-	 * @param {?Array}     after  Optional after value, to be appended in a new
-	 *                            paragraph block to the set of blocks passed
-	 *                            as spread.
-	 * @param {...WPBlock} blocks Optional blocks inserted between the before
-	 *                            and after value blocks.
-	 */
-	splitBlock( before, after, ...blocks ) {
-		const {
-			attributes,
-			insertBlocksAfter,
-			setAttributes,
-			onReplace,
-		} = this.props;
-
-		if ( after !== null ) {
-			// Append "After" content as a new paragraph block to the end of
-			// any other blocks being inserted after the current paragraph.
-			blocks.push( createBlock( name, { content: after } ) );
-		}
-
-		if ( blocks.length && insertBlocksAfter ) {
-			insertBlocksAfter( blocks );
-		}
-
-		const { content } = attributes;
-		if ( before === null ) {
-			// If before content is omitted, treat as intent to delete block.
-			onReplace( [] );
-		} else if ( content !== before ) {
-			// Only update content if it has in-fact changed. In case that user
-			// has created a new paragraph at end of an existing one, the value
-			// of before will be strictly equal to the current content.
-			setAttributes( { content: before } );
-		}
-	}
-
 	render() {
 		const {
 			attributes,
@@ -242,7 +198,7 @@ class ParagraphBlock extends Component {
 							content: nextContent,
 						} );
 					} }
-					unstableOnSplit={ this.splitBlock }
+					onSplit={ ( value ) => createBlock( name, { content: value } ) }
 					onMerge={ mergeBlocks }
 					onReplace={ this.onReplace }
 					onRemove={ () => onReplace( [] ) }

packages/e2e-tests/specs/splitting-merging.test.js

@@ -29,6 +29,9 @@ describe( 'splitting and merging blocks', () => {
 
 		// Press Backspace to merge paragraph blocks
 		await page.keyboard.press( 'Backspace' );
+		// At the moment, caret position is restored on the next call stack.
+		// eslint-disable-next-line no-restricted-syntax
+		await page.waitFor( 1 );
 
 		// Ensure that caret position is correctly placed at the between point.
 		await page.keyboard.type( 'Between' );
@@ -60,6 +63,9 @@ describe( 'splitting and merging blocks', () => {
 		await page.keyboard.type( 'Foo' );
 		await page.keyboard.press( 'Enter' );
 		await page.keyboard.press( 'Backspace' );
+		// At the moment, caret position is restored on the next call stack.
+		// eslint-disable-next-line no-restricted-syntax
+		await page.waitFor( 1 );
 
 		// Replace contents of first paragraph with "Bar".
 		await pressKeyTimes( 'Backspace', 4 );

packages/editor/src/components/block-list/block.js

@@ -746,8 +746,8 @@ const applyWithDispatch = withDispatch( ( dispatch, ownProps, { select } ) => {
 				}
 			}
 		},
-		onReplace( blocks ) {
-			replaceBlocks( [ ownProps.clientId ], blocks );
+		onReplace( blocks, index ) {
+			replaceBlocks( [ ownProps.clientId ], blocks, index );
 		},
 		onMetaChange( meta ) {
 			editPost( { meta } );

packages/editor/src/components/rich-text/README.md

@@ -25,9 +25,13 @@ Render a rich [`contenteditable` input](https://developer.mozilla.org/en-US/docs
 
 *Optional.* By default, a line break will be inserted on <kbd>Enter</kbd>. If the editable field can contain multiple paragraphs, this property can be set to create new paragraphs on <kbd>Enter</kbd>.
 
+### `onSplit( value: String ): Function`
+
+*Optional.* Called when the content can be split, where `value` is a priece of content being split off. Here you should create a new block with that content and return it. Note that you also need to provide `onReplace` in order for this to take any effect.
+
 ### `onReplace( blocks: Array ): Function`
 
-*Optional.* Called when the `RichText` instance is empty and it can be replaced with the given blocks.
+*Optional.* Called when the `RichText` instance can be replaced with the given blocks.
 
 ### `onMerge( forward: Boolean ): Function`