From 1d9a378c5426acaa3ffb84f9feab8bad2f55af4e Mon Sep 17 00:00:00 2001
From: Daniel Richards <daniel.richards@automattic.com>
Date: Tue, 16 Aug 2022 16:54:54 +0800
Subject: [PATCH 1/5] Refactor popover to use separate flip and resize props
 instead of forcePosition

---
 .../src/components/block-popover/inbetween.js       |  3 ++-
 .../src/components/block-popover/index.js           |  3 ++-
 .../block-tools/use-block-toolbar-popover-props.js  | 13 +++++++++----
 packages/components/src/popover/index.js            | 13 +++++++------
 packages/components/src/popover/stories/index.js    |  6 ++++--
 .../widgets/src/blocks/legacy-widget/edit/form.js   |  3 ++-
 6 files changed, 26 insertions(+), 15 deletions(-)

diff --git a/packages/block-editor/src/components/block-popover/inbetween.js b/packages/block-editor/src/components/block-popover/inbetween.js
index 37fb597d790b9c..a658cc5d077051 100644
--- a/packages/block-editor/src/components/block-popover/inbetween.js
+++ b/packages/block-editor/src/components/block-popover/inbetween.js
@@ -186,7 +186,8 @@ function BlockPopoverInbetween( {
 				'block-editor-block-popover__inbetween',
 				props.className
 			) }
-			__unstableForcePosition
+			__unstableResize={ false }
+			__unstableFlip={ false }
 		>
 			<div style={ style }>{ children }</div>
 		</Popover>
diff --git a/packages/block-editor/src/components/block-popover/index.js b/packages/block-editor/src/components/block-popover/index.js
index 15be18b0a8c82e..4e267762920d25 100644
--- a/packages/block-editor/src/components/block-popover/index.js
+++ b/packages/block-editor/src/components/block-popover/index.js
@@ -66,7 +66,8 @@ function BlockPopover(
 			// Render in the old slot if needed for backward compatibility,
 			// otherwise render in place (not in the default popover slot).
 			__unstableSlotName={ __unstablePopoverSlot || null }
-			__unstableForcePosition
+			__unstableResize={ false }
+			__unstableFlip={ false }
 			__unstableShift
 			{ ...props }
 			className={ classnames(
diff --git a/packages/block-editor/src/components/block-tools/use-block-toolbar-popover-props.js b/packages/block-editor/src/components/block-tools/use-block-toolbar-popover-props.js
index 3d42e994f5943f..7b63951fc628ee 100644
--- a/packages/block-editor/src/components/block-tools/use-block-toolbar-popover-props.js
+++ b/packages/block-editor/src/components/block-tools/use-block-toolbar-popover-props.js
@@ -14,14 +14,19 @@ import { __unstableUseBlockElement as useBlockElement } from '../block-list/use-
 // By default the toolbar sets the `shift` prop. If the user scrolls the page
 // down the toolbar will stay on screen by adopting a sticky position at the
 // top of the viewport.
-const DEFAULT_PROPS = { __unstableForcePosition: true, __unstableShift: true };
+const DEFAULT_PROPS = {
+	__unstableResize: false,
+	__unstableFlip: false,
+	__unstableShift: true,
+};
 
 // When there isn't enough height between the top of the block and the editor
 // canvas, the `shift` prop is set to `false`, as it will cause the block to be
-// obscured. The `flip` behavior is enabled (by setting `forcePosition` to
-// `false`), which positions the toolbar below the block.
+// obscured. The `flip` behavior is enabled, which positions the toolbar below
+// the block.
 const RESTRICTED_HEIGHT_PROPS = {
-	__unstableForcePosition: false,
+	__unstableResize: false,
+	__unstableFlip: true,
 	__unstableShift: false,
 };
 
diff --git a/packages/components/src/popover/index.js b/packages/components/src/popover/index.js
index 67e7c0abc89e90..a89818d325c818 100644
--- a/packages/components/src/popover/index.js
+++ b/packages/components/src/popover/index.js
@@ -143,7 +143,8 @@ const Popover = (
 		expandOnMobile,
 		onFocusOutside,
 		__unstableSlotName = SLOT_NAME,
-		__unstableForcePosition = false,
+		__unstableFlip = true,
+		__unstableResize = true,
 		__unstableShift = false,
 		...contentProps
 	},
@@ -232,10 +233,9 @@ const Popover = (
 				crossAxis: frameOffsetRef.current[ crossAxis ],
 			};
 		} ),
-		__unstableForcePosition ? undefined : flip(),
-		__unstableForcePosition
-			? undefined
-			: size( {
+		__unstableFlip ? flip() : undefined,
+		__unstableResize
+			? size( {
 					apply( sizeProps ) {
 						const { availableHeight } = sizeProps;
 						if ( ! refs.floating.current ) return;
@@ -245,7 +245,8 @@ const Popover = (
 							overflow: 'auto',
 						} );
 					},
-			  } ),
+			  } )
+			: undefined,
 		__unstableShift
 			? shift( {
 					crossAxis: true,
diff --git a/packages/components/src/popover/stories/index.js b/packages/components/src/popover/stories/index.js
index cc9b3a8e85ed49..e13ea01ed33dc9 100644
--- a/packages/components/src/popover/stories/index.js
+++ b/packages/components/src/popover/stories/index.js
@@ -73,7 +73,8 @@ export default {
 			options: AVAILABLE_POSITIONS,
 		},
 		__unstableSlotName: { control: { type: null } },
-		__unstableForcePosition: { control: { type: 'boolean' } },
+		__unstableResize: { control: { type: 'boolean' } },
+		__unstableFlip: { control: { type: 'boolean' } },
 		__unstableShift: { control: { type: 'boolean' } },
 	},
 };
@@ -180,7 +181,8 @@ AllPlacements.args = {
 	),
 	noArrow: false,
 	offset: 10,
-	__unstableForcePosition: true,
+	__unstableResize: false,
+	__unstableFlip: false,
 };
 
 export const DynamicHeight = ( { children, ...args } ) => {
diff --git a/packages/widgets/src/blocks/legacy-widget/edit/form.js b/packages/widgets/src/blocks/legacy-widget/edit/form.js
index dd0fcb57baebcd..1e4d5688c81b5a 100644
--- a/packages/widgets/src/blocks/legacy-widget/edit/form.js
+++ b/packages/widgets/src/blocks/legacy-widget/edit/form.js
@@ -105,7 +105,8 @@ export default function Form( {
 					focusOnMount={ false }
 					placement="right"
 					offset={ 32 }
-					__unstableForcePosition
+					__unstableResize={ false }
+					__unstableFlip={ false }
 					__unstableShift
 				>
 					<div

From da73a3ae091ccbbabbaf05ece7971ef8ed16898d Mon Sep 17 00:00:00 2001
From: Daniel Richards <daniel.richards@automattic.com>
Date: Wed, 24 Aug 2022 14:05:39 +0800
Subject: [PATCH 2/5] Update changelog

---
 packages/components/CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
index ca4cc66bc63f5b..5f44cb51d7ee25 100644
--- a/packages/components/CHANGELOG.md
+++ b/packages/components/CHANGELOG.md
@@ -83,6 +83,7 @@
 ### Experimental
 
 -   `FormTokenField`: add `__experimentalAutoSelectFirstMatch` prop to auto select the first matching suggestion on typing ([#42527](https://github.com/WordPress/gutenberg/pull/42527/)).
+-   `Popover`: Refactor `__unstableForcePosition` to separate `__unstableFlip` and `__unstableResize` props ([#43546](https://github.com/WordPress/gutenberg/pull/43546/)).
 
 ## 19.17.0 (2022-08-10)
 

From 436ca08ab3657e53adb0f62c4a398f041d4704a2 Mon Sep 17 00:00:00 2001
From: Daniel Richards <daniel.richards@automattic.com>
Date: Thu, 25 Aug 2022 10:33:23 +0800
Subject: [PATCH 3/5] Add back compat and deprecation message for
 __unstableForcePosition

---
 packages/components/src/popover/index.js | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/packages/components/src/popover/index.js b/packages/components/src/popover/index.js
index a89818d325c818..abd7f4b3953f23 100644
--- a/packages/components/src/popover/index.js
+++ b/packages/components/src/popover/index.js
@@ -146,6 +146,7 @@ const Popover = (
 		__unstableFlip = true,
 		__unstableResize = true,
 		__unstableShift = false,
+		__unstableForcePosition = false,
 		...contentProps
 	},
 	forwardedRef
@@ -157,6 +158,20 @@ const Popover = (
 		} );
 	}
 
+	if ( __unstableForcePosition ) {
+		deprecated( '__unstableForcePosition prop in Popover component', {
+			since: '6.1',
+			version: '6.3',
+			alternative:
+				'`__unstableFlip={ false }` and  `__unstableResize={ false }`',
+		} );
+
+		// Back-compat, set the `__unstableFlip` and `__unstableResize` props
+		// to `false` to replicate `__unstableForcePosition`.
+		__unstableFlip = false;
+		__unstableResize = false;
+	}
+
 	const arrowRef = useRef( null );
 	const anchorRefFallback = useRef( null );
 

From 811c0262d53aa8a9ef2d7b54e0cfc5818ac31044 Mon Sep 17 00:00:00 2001
From: Daniel Richards <daniel.richards@automattic.com>
Date: Thu, 25 Aug 2022 10:45:01 +0800
Subject: [PATCH 4/5] Stabilize flip and resize

---
 .../src/components/block-popover/inbetween.js |  4 ++--
 .../src/components/block-popover/index.js     |  4 ++--
 .../use-block-toolbar-popover-props.js        |  8 ++++----
 packages/components/CHANGELOG.md              |  3 ++-
 packages/components/src/popover/README.md     | 20 +++++++++++++++++++
 packages/components/src/popover/index.js      | 19 +++++++++---------
 .../components/src/popover/stories/index.js   |  8 ++++----
 .../src/blocks/legacy-widget/edit/form.js     |  4 ++--
 8 files changed, 45 insertions(+), 25 deletions(-)

diff --git a/packages/block-editor/src/components/block-popover/inbetween.js b/packages/block-editor/src/components/block-popover/inbetween.js
index a658cc5d077051..f68a7532f58b83 100644
--- a/packages/block-editor/src/components/block-popover/inbetween.js
+++ b/packages/block-editor/src/components/block-popover/inbetween.js
@@ -186,8 +186,8 @@ function BlockPopoverInbetween( {
 				'block-editor-block-popover__inbetween',
 				props.className
 			) }
-			__unstableResize={ false }
-			__unstableFlip={ false }
+			resize={ false }
+			flip={ false }
 		>
 			<div style={ style }>{ children }</div>
 		</Popover>
diff --git a/packages/block-editor/src/components/block-popover/index.js b/packages/block-editor/src/components/block-popover/index.js
index 4e267762920d25..06b878e618be17 100644
--- a/packages/block-editor/src/components/block-popover/index.js
+++ b/packages/block-editor/src/components/block-popover/index.js
@@ -66,8 +66,8 @@ function BlockPopover(
 			// Render in the old slot if needed for backward compatibility,
 			// otherwise render in place (not in the default popover slot).
 			__unstableSlotName={ __unstablePopoverSlot || null }
-			__unstableResize={ false }
-			__unstableFlip={ false }
+			resize={ false }
+			flip={ false }
 			__unstableShift
 			{ ...props }
 			className={ classnames(
diff --git a/packages/block-editor/src/components/block-tools/use-block-toolbar-popover-props.js b/packages/block-editor/src/components/block-tools/use-block-toolbar-popover-props.js
index 7b63951fc628ee..fdbf5831ae98a1 100644
--- a/packages/block-editor/src/components/block-tools/use-block-toolbar-popover-props.js
+++ b/packages/block-editor/src/components/block-tools/use-block-toolbar-popover-props.js
@@ -15,8 +15,8 @@ import { __unstableUseBlockElement as useBlockElement } from '../block-list/use-
 // down the toolbar will stay on screen by adopting a sticky position at the
 // top of the viewport.
 const DEFAULT_PROPS = {
-	__unstableResize: false,
-	__unstableFlip: false,
+	resize: false,
+	flip: false,
 	__unstableShift: true,
 };
 
@@ -25,8 +25,8 @@ const DEFAULT_PROPS = {
 // obscured. The `flip` behavior is enabled, which positions the toolbar below
 // the block.
 const RESTRICTED_HEIGHT_PROPS = {
-	__unstableResize: false,
-	__unstableFlip: true,
+	resize: false,
+	flip: true,
 	__unstableShift: false,
 };
 
diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
index 5f44cb51d7ee25..5459fa35d806a2 100644
--- a/packages/components/CHANGELOG.md
+++ b/packages/components/CHANGELOG.md
@@ -43,6 +43,7 @@
 -   `FormTokenField`: Refactor away from `_.difference()` ([#43224](https://github.com/WordPress/gutenberg/pull/43224/)).
 -   `Autocomplete`: use `KeyboardEvent.code` instead of `KeyboardEvent.keyCode` ([#43432](https://github.com/WordPress/gutenberg/pull/43432/)).
 -   `ConfirmDialog`: replace (almost) every usage of `fireEvent` with `@testing-library/user-event`  ([#43429](https://github.com/WordPress/gutenberg/pull/43429/)).
+-   `Popover`: Introduce new `flip` and `resize` props ([#43546](https://github.com/WordPress/gutenberg/pull/43546/)).
 
 ### Internal
 
@@ -83,7 +84,7 @@
 ### Experimental
 
 -   `FormTokenField`: add `__experimentalAutoSelectFirstMatch` prop to auto select the first matching suggestion on typing ([#42527](https://github.com/WordPress/gutenberg/pull/42527/)).
--   `Popover`: Refactor `__unstableForcePosition` to separate `__unstableFlip` and `__unstableResize` props ([#43546](https://github.com/WordPress/gutenberg/pull/43546/)).
+-   `Popover`: Deprecate `__unstableForcePosition`, now replaced by new `flip` and `resize` props ([#43546](https://github.com/WordPress/gutenberg/pull/43546/)).
 
 ## 19.17.0 (2022-08-10)
 
diff --git a/packages/components/src/popover/README.md b/packages/components/src/popover/README.md
index 3031798a5af9cb..6dfd1f6bdd7243 100644
--- a/packages/components/src/popover/README.md
+++ b/packages/components/src/popover/README.md
@@ -71,6 +71,26 @@ Each of these base placements has an alignment in the form -start and -end. For
 -   Required: No
 -   Default: `"bottom-start"`
 
+### flip
+
+Specifies whether the `Popover` should flip across its axis if there isn't space for it in the normal placement.
+
+When the using a 'top' placement, the `Popover` will switch to a 'bottom' placement. When using a 'left' placement, the popover will switch to a 'right' placement.
+
+The `Popover` will retain its alignment of 'start' or 'end' when flipping.
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `true`
+
+### resize
+
+Adjusts the height of the `Popover` to prevent overflow.
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `true`
+
 ### offset
 
 The distance (in pixels) between the anchor and popover.
diff --git a/packages/components/src/popover/index.js b/packages/components/src/popover/index.js
index abd7f4b3953f23..0fde37123d273d 100644
--- a/packages/components/src/popover/index.js
+++ b/packages/components/src/popover/index.js
@@ -5,7 +5,7 @@
 import classnames from 'classnames';
 import {
 	useFloating,
-	flip,
+	flip as flipMiddleware,
 	shift,
 	autoUpdate,
 	arrow,
@@ -143,8 +143,8 @@ const Popover = (
 		expandOnMobile,
 		onFocusOutside,
 		__unstableSlotName = SLOT_NAME,
-		__unstableFlip = true,
-		__unstableResize = true,
+		flip = true,
+		resize = true,
 		__unstableShift = false,
 		__unstableForcePosition = false,
 		...contentProps
@@ -162,14 +162,13 @@ const Popover = (
 		deprecated( '__unstableForcePosition prop in Popover component', {
 			since: '6.1',
 			version: '6.3',
-			alternative:
-				'`__unstableFlip={ false }` and  `__unstableResize={ false }`',
+			alternative: '`flip={ false }` and  `resize={ false }`',
 		} );
 
-		// Back-compat, set the `__unstableFlip` and `__unstableResize` props
+		// Back-compat, set the `flip` and `resize` props
 		// to `false` to replicate `__unstableForcePosition`.
-		__unstableFlip = false;
-		__unstableResize = false;
+		flip = false;
+		resize = false;
 	}
 
 	const arrowRef = useRef( null );
@@ -248,8 +247,8 @@ const Popover = (
 				crossAxis: frameOffsetRef.current[ crossAxis ],
 			};
 		} ),
-		__unstableFlip ? flip() : undefined,
-		__unstableResize
+		flip ? flipMiddleware() : undefined,
+		resize
 			? size( {
 					apply( sizeProps ) {
 						const { availableHeight } = sizeProps;
diff --git a/packages/components/src/popover/stories/index.js b/packages/components/src/popover/stories/index.js
index e13ea01ed33dc9..ee2991105b130b 100644
--- a/packages/components/src/popover/stories/index.js
+++ b/packages/components/src/popover/stories/index.js
@@ -73,8 +73,8 @@ export default {
 			options: AVAILABLE_POSITIONS,
 		},
 		__unstableSlotName: { control: { type: null } },
-		__unstableResize: { control: { type: 'boolean' } },
-		__unstableFlip: { control: { type: 'boolean' } },
+		resize: { control: { type: 'boolean' } },
+		flip: { control: { type: 'boolean' } },
 		__unstableShift: { control: { type: 'boolean' } },
 	},
 };
@@ -181,8 +181,8 @@ AllPlacements.args = {
 	),
 	noArrow: false,
 	offset: 10,
-	__unstableResize: false,
-	__unstableFlip: false,
+	resize: false,
+	flip: false,
 };
 
 export const DynamicHeight = ( { children, ...args } ) => {
diff --git a/packages/widgets/src/blocks/legacy-widget/edit/form.js b/packages/widgets/src/blocks/legacy-widget/edit/form.js
index 1e4d5688c81b5a..0498587f2a3ccb 100644
--- a/packages/widgets/src/blocks/legacy-widget/edit/form.js
+++ b/packages/widgets/src/blocks/legacy-widget/edit/form.js
@@ -105,8 +105,8 @@ export default function Form( {
 					focusOnMount={ false }
 					placement="right"
 					offset={ 32 }
-					__unstableResize={ false }
-					__unstableFlip={ false }
+					resize={ false }
+					flip={ false }
 					__unstableShift
 				>
 					<div

From 13d941a8a8676dac4cc92c52763281010ed0c975 Mon Sep 17 00:00:00 2001
From: Daniel Richards <daniel.richards@automattic.com>
Date: Mon, 29 Aug 2022 08:00:53 +1000
Subject: [PATCH 5/5] Remove default value for __unstableForcePosition, and
 ensure deprecation message is shown whenever the prop is explicitly specified

---
 packages/components/src/popover/index.js | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/components/src/popover/index.js b/packages/components/src/popover/index.js
index 0fde37123d273d..269c15d946df3a 100644
--- a/packages/components/src/popover/index.js
+++ b/packages/components/src/popover/index.js
@@ -146,7 +146,7 @@ const Popover = (
 		flip = true,
 		resize = true,
 		__unstableShift = false,
-		__unstableForcePosition = false,
+		__unstableForcePosition,
 		...contentProps
 	},
 	forwardedRef
@@ -158,7 +158,7 @@ const Popover = (
 		} );
 	}
 
-	if ( __unstableForcePosition ) {
+	if ( __unstableForcePosition !== undefined ) {
 		deprecated( '__unstableForcePosition prop in Popover component', {
 			since: '6.1',
 			version: '6.3',
@@ -167,8 +167,8 @@ const Popover = (
 
 		// Back-compat, set the `flip` and `resize` props
 		// to `false` to replicate `__unstableForcePosition`.
-		flip = false;
-		resize = false;
+		flip = ! __unstableForcePosition;
+		resize = ! __unstableForcePosition;
 	}
 
 	const arrowRef = useRef( null );