Partial revert

docs/reference-guides/data/data-core-block-editor.md

@@ -160,22 +160,16 @@ _Returns_
 
 <a name="getBlockInsertionPoint" href="#getBlockInsertionPoint">#</a> **getBlockInsertionPoint**
 
-Returns the insertion point. This will be:
-
-1. The insertion point manually set using setInsertionPoint() or
-   showInsertionPoint(); or
-2. The point after the current block selection, if there is a selection; or
-3. The point at the end of the block list.
-
-Components like <Inserter> will default to inserting blocks at this point.
+Returns the insertion point, the index at which the new inserted block would
+be placed. Defaults to the last index.
 
 _Parameters_
 
--   _state_ `Object`: Global application state.
+-   _state_ `Object`: Editor state.
 
 _Returns_
 
--   `Object`: Insertion point object with `rootClientId` and `index`.
+-   `Object`: Insertion point object with `rootClientId`, `index`.
 
 <a name="getBlockListSettings" href="#getBlockListSettings">#</a> **getBlockListSettings**
 
@@ -853,16 +847,15 @@ _Returns_
 
 <a name="isBlockInsertionPointVisible" href="#isBlockInsertionPointVisible">#</a> **isBlockInsertionPointVisible**
 
-Whether or not the insertion point should be shown to users. This is set
-using showInsertionPoint() or hideInsertionPoint().
+Returns true if we should show the block insertion point.
 
 _Parameters_
 
 -   _state_ `Object`: Global application state.
 
 _Returns_
 
--   `?boolean`: Whether the insertion point should be shown.
+-   `?boolean`: Whether the insertion point is visible or not.
 
 <a name="isBlockMultiSelected" href="#isBlockMultiSelected">#</a> **isBlockMultiSelected**
 
@@ -1090,7 +1083,7 @@ _Parameters_
 
 <a name="hideInsertionPoint" href="#hideInsertionPoint">#</a> **hideInsertionPoint**
 
-Hides the insertion point for users.
+Returns an action object hiding the insertion point.
 
 _Returns_
 
@@ -1406,14 +1399,13 @@ _Returns_
 
 <a name="showInsertionPoint" href="#showInsertionPoint">#</a> **showInsertionPoint**
 
-Sets the insertion point and shows it to users.
-
-Components like <Inserter> will default to inserting blocks at this point.
+Returns an action object used in signalling that the insertion point should
+be shown.
 
 _Parameters_
 
--   _rootClientId_ `?string`: Root client ID of block list in which to insert. Use `undefined` for the root block list.
--   _index_ `number`: Index at which block should be inserted.
+-   _rootClientId_ `?string`: Optional root client ID of block list on which to insert.
+-   _index_ `?number`: Index at which block should be inserted.
 
 _Returns_
 

packages/block-editor/src/store/actions.js

@@ -620,34 +620,12 @@ export function* insertBlocks(
 }
 
 /**
- * Sets the insertion point without showing it to users.
+ * Returns an action object used in signalling that the insertion point should
+ * be shown.
  *
- * Components like <Inserter> will default to inserting blocks at this point.
- *
- * @param {?string} rootClientId Root client ID of block list in which to
- *                               insert. Use `undefined` for the root block
- *                               list.
- * @param {number} index         Index at which block should be inserted.
- *
- * @return {Object} Action object.
- */
-export function __unstableSetInsertionPoint( rootClientId, index ) {
-	return {
-		type: 'SET_INSERTION_POINT',
-		rootClientId,
-		index,
-	};
-}
-
-/**
- * Sets the insertion point and shows it to users.
- *
- * Components like <Inserter> will default to inserting blocks at this point.
- *
- * @param {?string} rootClientId Root client ID of block list in which to
- *                               insert. Use `undefined` for the root block
- *                               list.
- * @param {number} index         Index at which block should be inserted.
+ * @param {?string} rootClientId Optional root client ID of block list on
+ *                               which to insert.
+ * @param {?number} index        Index at which block should be inserted.
  *
  * @return {Object} Action object.
  */
@@ -660,7 +638,7 @@ export function showInsertionPoint( rootClientId, index ) {
 }
 
 /**
- * Hides the insertion point for users.
+ * Returns an action object hiding the insertion point.
  *
  * @return {Object} Action object.
  */

packages/block-editor/src/store/reducer.js

@@ -1393,32 +1393,9 @@ export function blocksMode( state = {}, action ) {
 }
 
 /**
- * A helper for resetting the insertion point state.
- *
- * @param {Object} state        Current state.
- * @param {Object} action       Dispatched action.
- * @param {*}      defaultValue The default value for the reducer.
- *
- * @return {*} Either the default value if a reset is required, or the state.
- */
-function resetInsertionPoint( state, action, defaultValue ) {
-	switch ( action.type ) {
-		case 'CLEAR_SELECTED_BLOCK':
-		case 'SELECT_BLOCK':
-		case 'SELECTION_CHANGE':
-		case 'REPLACE_INNER_BLOCKS':
-		case 'INSERT_BLOCKS':
-		case 'REMOVE_BLOCKS':
-		case 'REPLACE_BLOCKS':
-			return defaultValue;
-	}
-
-	return state;
-}
-
-/**
- * Reducer returning the insertion point position, consisting of the
- * rootClientId and an index.
+ * Reducer returning the block insertion point visibility, either null if there
+ * is not an explicit insertion point assigned, or an object of its `index` and
+ * `rootClientId`.
  *
  * @param {Object} state  Current state.
  * @param {Object} action Dispatched action.
@@ -1427,33 +1404,15 @@ function resetInsertionPoint( state, action, defaultValue ) {
  */
 export function insertionPoint( state = null, action ) {
 	switch ( action.type ) {
-		case 'SET_INSERTION_POINT':
-		case 'SHOW_INSERTION_POINT': {
+		case 'SHOW_INSERTION_POINT':
 			const { rootClientId, index } = action;
 			return { rootClientId, index };
-		}
-	}
-
-	return resetInsertionPoint( state, action, null );
-}
 
-/**
- * Reducer returning the visibility of the insertion point.
- *
- * @param {Object} state  Current state.
- * @param {Object} action Dispatched action.
- *
- * @return {Object} Updated state.
- */
-export function insertionPointVisibility( state = false, action ) {
-	switch ( action.type ) {
-		case 'SHOW_INSERTION_POINT':
-			return true;
 		case 'HIDE_INSERTION_POINT':
-			return false;
+			return null;
 	}
 
-	return resetInsertionPoint( state, action, false );
+	return state;
 }
 
 /**
@@ -1764,7 +1723,6 @@ export default combineReducers( {
 	blocksMode,
 	blockListSettings,
 	insertionPoint,
-	insertionPointVisibility,
 	template,
 	settings,
 	preferences,

packages/block-editor/src/store/selectors.js

@@ -1177,18 +1177,12 @@ export function isCaretWithinFormattedText( state ) {
 }
 
 /**
- * Returns the insertion point. This will be:
+ * Returns the insertion point, the index at which the new inserted block would
+ * be placed. Defaults to the last index.
  *
- * 1) The insertion point manually set using setInsertionPoint() or
- *    showInsertionPoint(); or
- * 2) The point after the current block selection, if there is a selection; or
- * 3) The point at the end of the block list.
- *
- * Components like <Inserter> will default to inserting blocks at this point.
- *
- * @param {Object} state Global application state.
+ * @param {Object} state Editor state.
  *
- * @return {Object} Insertion point object with `rootClientId` and `index`.
+ * @return {Object} Insertion point object with `rootClientId`, `index`.
  */
 export function getBlockInsertionPoint( state ) {
 	let rootClientId, index;
@@ -1214,15 +1208,14 @@ export function getBlockInsertionPoint( state ) {
 }
 
 /**
- * Whether or not the insertion point should be shown to users. This is set
- * using showInsertionPoint() or hideInsertionPoint().
+ * Returns true if we should show the block insertion point.
  *
  * @param {Object} state Global application state.
  *
- * @return {?boolean} Whether the insertion point should be shown.
+ * @return {?boolean} Whether the insertion point is visible or not.
  */
 export function isBlockInsertionPointVisible( state ) {
-	return state.insertionPointVisibility;
+	return state.insertionPoint !== null;
 }
 
 /**

packages/block-editor/src/store/test/actions.js

@@ -42,7 +42,6 @@ const {
 	resetBlocks,
 	selectBlock,
 	selectPreviousBlock,
-	__unstableSetInsertionPoint,
 	showInsertionPoint,
 	startMultiSelect,
 	startTyping,
@@ -741,31 +740,11 @@ describe( 'actions', () => {
 		} );
 	} );
 
-	describe( '__unstableSetInsertionPoint', () => {
-		it( 'should return the SET_INSERTION_POINT action', () => {
-			expect( __unstableSetInsertionPoint() ).toEqual( {
-				type: 'SET_INSERTION_POINT',
-			} );
-			expect( __unstableSetInsertionPoint( 'rootClientId', 2 ) ).toEqual(
-				{
-					type: 'SET_INSERTION_POINT',
-					rootClientId: 'rootClientId',
-					index: 2,
-				}
-			);
-		} );
-	} );
-
 	describe( 'showInsertionPoint', () => {
 		it( 'should return the SHOW_INSERTION_POINT action', () => {
 			expect( showInsertionPoint() ).toEqual( {
 				type: 'SHOW_INSERTION_POINT',
 			} );
-			expect( showInsertionPoint( 'rootClientId', 2 ) ).toEqual( {
-				type: 'SHOW_INSERTION_POINT',
-				rootClientId: 'rootClientId',
-				index: 2,
-			} );
 		} );
 	} );
 

packages/block-editor/src/store/test/reducer.js

@@ -29,7 +29,6 @@ import {
 	preferences,
 	blocksMode,
 	insertionPoint,
-	insertionPointVisibility,
 	template,
 	blockListSettings,
 	lastBlockAttributesChange,
@@ -2041,82 +2040,35 @@ describe( 'state', () => {
 	} );
 
 	describe( 'insertionPoint', () => {
-		it( 'defaults to `null`', () => {
+		it( 'should default to null', () => {
 			const state = insertionPoint( undefined, {} );
 
-			expect( state ).toEqual( null );
+			expect( state ).toBe( null );
 		} );
 
-		it.each( [ 'SET_INSERTION_POINT', 'SHOW_INSERTION_POINT' ] )(
-			'sets the insertion point on %s',
-			( type ) => {
-				const original = deepFreeze( {
-					rootClientId: 'clientId1',
-					index: 0,
-				} );
-
-				const expectedNewState = {
-					rootClientId: 'clientId2',
-					index: 1,
-				};
-
-				const state = insertionPoint( original, {
-					type,
-					...expectedNewState,
-				} );
-
-				expect( state ).toEqual( expectedNewState );
-			}
-		);
-
-		it.each( [
-			'CLEAR_SELECTED_BLOCK',
-			'SELECT_BLOCK',
-			'REPLACE_INNER_BLOCKS',
-			'INSERT_BLOCKS',
-			'REMOVE_BLOCKS',
-			'REPLACE_BLOCKS',
-		] )( 'resets the insertion point to `null` on %s', ( type ) => {
-			const original = deepFreeze( {
+		it( 'should set insertion point', () => {
+			const state = insertionPoint( null, {
+				type: 'SHOW_INSERTION_POINT',
 				rootClientId: 'clientId1',
 				index: 0,
 			} );
-			const state = insertionPoint( original, {
-				type,
-			} );
-
-			expect( state ).toEqual( null );
-		} );
-	} );
-
-	describe( 'insertionPointVisibility', () => {
-		it( 'defaults to `false`', () => {
-			const state = insertionPointVisibility( undefined, {} );
-			expect( state ).toBe( false );
-		} );
 
-		it( 'shows the insertion point', () => {
-			const state = insertionPointVisibility( false, {
-				type: 'SHOW_INSERTION_POINT',
+			expect( state ).toEqual( {
+				rootClientId: 'clientId1',
+				index: 0,
 			} );
-
-			expect( state ).toBe( true );
 		} );
 
-		it.each( [
-			'HIDE_INSERTION_POINT',
-			'CLEAR_SELECTED_BLOCK',
-			'SELECT_BLOCK',
-			'REPLACE_INNER_BLOCKS',
-			'INSERT_BLOCKS',
-			'REMOVE_BLOCKS',
-			'REPLACE_BLOCKS',
-		] )( 'sets the insertion point on %s to `false`', ( type ) => {
-			const state = insertionPointVisibility( true, {
-				type,
+		it( 'should clear the insertion point', () => {
+			const original = deepFreeze( {
+				rootClientId: 'clientId1',
+				index: 0,
+			} );
+			const state = insertionPoint( original, {
+				type: 'HIDE_INSERTION_POINT',
 			} );
 
-			expect( state ).toBe( false );
+			expect( state ).toBe( null );
 		} );
 	} );