From 349ccc48e6e0c81bb62861eb03926d3a913e4de0 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Thu, 10 Mar 2022 01:56:37 +0900
Subject: [PATCH 1/5] BaseControl: Add opt-in prop for margin-free styles

---
 .../components/src/base-control/README.md     | 10 +++++-
 packages/components/src/base-control/index.js | 32 +++++++++++--------
 .../src/base-control/stories/index.js         |  1 +
 .../styles/base-control-styles.js             | 11 ++++++-
 4 files changed, 39 insertions(+), 15 deletions(-)

diff --git a/packages/components/src/base-control/README.md b/packages/components/src/base-control/README.md
index 6ed5b75b76b33..dbb3e66b4464b 100644
--- a/packages/components/src/base-control/README.md
+++ b/packages/components/src/base-control/README.md
@@ -10,7 +10,7 @@ Render a BaseControl for a textarea input:
 import { BaseControl } from '@wordpress/components';
 
 const MyBaseControl = () => (
-	<BaseControl id="textarea-1" label="Text" help="Enter some text">
+	<BaseControl id="textarea-1" label="Text" help="Enter some text" __nextHasNoMarginBottom={ true }>
 		<textarea id="textarea-1" />
 	</BaseControl>
 );
@@ -63,6 +63,14 @@ The content to be displayed within the BaseControl.
 -   Type: `Element`
 -   Required: Yes
 
+### __nextHasNoMarginBottom
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `false`
+
+Start opting into the new margin-free styles that will become the default in a future version.
+
 ## BaseControl.VisualLabel
 
 `BaseControl.VisualLabel` component is used to render a purely visual label inside a `BaseControl` component.
diff --git a/packages/components/src/base-control/index.js b/packages/components/src/base-control/index.js
index 86746d6174fd6..9762a65ad94f7 100644
--- a/packages/components/src/base-control/index.js
+++ b/packages/components/src/base-control/index.js
@@ -17,18 +17,19 @@ import {
 
 /**
  * @typedef Props
- * @property {string}                    [id]                  The id of the element to which labels and help text are being generated.
- *                                                             That element should be passed as a child.
- * @property {import('react').ReactNode} help                  If this property is added, a help text will be
- *                                                             generated using help property as the content.
- * @property {import('react').ReactNode} [label]               If this property is added, a label will be generated
- *                                                             using label property as the content.
- * @property {boolean}                   [hideLabelFromVision] If true, the label will only be visible to screen readers.
- * @property {string}                    [className]           The class that will be added with "components-base-control" to the
- *                                                             classes of the wrapper div. If no className is passed only
- *                                                             components-base-control is used.
- * @property {import('react').ReactNode} [children]            The content to be displayed within
- *                                                             the BaseControl.
+ * @property {boolean}                   [__nextHasNoMarginBottom] Start opting into the new margin-free styles that will become the default in a future version.
+ * @property {string}                    [id]                      The id of the element to which labels and help text are being generated.
+ *                                                                 That element should be passed as a child.
+ * @property {import('react').ReactNode} help                      If this property is added, a help text will be
+ *                                                                 generated using help property as the content.
+ * @property {import('react').ReactNode} [label]                   If this property is added, a label will be generated
+ *                                                                 using label property as the content.
+ * @property {boolean}                   [hideLabelFromVision]     If true, the label will only be visible to screen readers.
+ * @property {string}                    [className]               The class that will be added with "components-base-control" to the
+ *                                                                 classes of the wrapper div. If no className is passed only
+ *                                                                 components-base-control is used.
+ * @property {import('react').ReactNode} [children]                The content to be displayed within
+ *                                                                 the BaseControl.
  */
 
 /**
@@ -36,6 +37,7 @@ import {
  * @return {JSX.Element} Element
  */
 function BaseControl( {
+	__nextHasNoMarginBottom = false,
 	id,
 	label,
 	hideLabelFromVision,
@@ -47,7 +49,11 @@ function BaseControl( {
 		<Wrapper
 			className={ classnames( 'components-base-control', className ) }
 		>
-			<StyledField className="components-base-control__field">
+			<StyledField
+				className="components-base-control__field"
+				// TODO: Official deprecation for this should start after all internal usages have been migrated
+				__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+			>
 				{ label &&
 					id &&
 					( hideLabelFromVision ? (
diff --git a/packages/components/src/base-control/stories/index.js b/packages/components/src/base-control/stories/index.js
index 53b09aba82507..6c51ddc17a5ac 100644
--- a/packages/components/src/base-control/stories/index.js
+++ b/packages/components/src/base-control/stories/index.js
@@ -22,6 +22,7 @@ const BaseControlWithTextarea = ( { id, ...props } ) => {
 
 export const Default = BaseControlWithTextarea.bind( {} );
 Default.args = {
+	__nextHasNoMarginBottom: true,
 	id: 'textarea-1',
 	label: '',
 	hideLabelFromVision: false,
diff --git a/packages/components/src/base-control/styles/base-control-styles.js b/packages/components/src/base-control/styles/base-control-styles.js
index 9255c818583da..2c9e7d3ee954c 100644
--- a/packages/components/src/base-control/styles/base-control-styles.js
+++ b/packages/components/src/base-control/styles/base-control-styles.js
@@ -15,8 +15,16 @@ export const Wrapper = styled.div`
 	font-size: ${ font( 'default.fontSize' ) };
 `;
 
+const deprecatedMargin = ( { __nextHasNoMarginBottom = false } ) => {
+	return ! __nextHasNoMarginBottom
+		? css`
+				margin-bottom: ${ space( 2 ) };
+		  `
+		: undefined;
+};
+
 export const StyledField = styled.div`
-	margin-bottom: ${ space( 2 ) };
+	${ deprecatedMargin }
 
 	.components-panel__row & {
 		margin-bottom: inherit;
@@ -33,6 +41,7 @@ export const StyledLabel = styled.label`
 `;
 
 export const StyledHelp = styled.p`
+	margin-top: ${ space( 2 ) };
 	font-size: ${ font( 'helpText.fontSize' ) };
 	font-style: normal;
 	color: ${ COLORS.mediumGray.text };

From 15095fb9be468299c420de19a3c5cbe5cb9b9bfa Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Thu, 10 Mar 2022 03:41:00 +0900
Subject: [PATCH 2/5] Fix story

`<TextareaControl>` is actually built with `BaseControl` already. Woops, BaseControl-ception.
---
 packages/components/src/base-control/stories/index.js | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/components/src/base-control/stories/index.js b/packages/components/src/base-control/stories/index.js
index 6c51ddc17a5ac..ed23809384622 100644
--- a/packages/components/src/base-control/stories/index.js
+++ b/packages/components/src/base-control/stories/index.js
@@ -4,7 +4,6 @@
 import BaseControl from '../';
 import Button from '../../button';
 import { Spacer } from '../../spacer';
-import TextareaControl from '../../textarea-control';
 
 export default {
 	title: 'Components/BaseControl',
@@ -15,7 +14,7 @@ export default {
 const BaseControlWithTextarea = ( { id, ...props } ) => {
 	return (
 		<BaseControl id={ id } { ...props }>
-			<TextareaControl id={ id } />
+			<textarea style={ { display: 'block' } } id={ id } />
 		</BaseControl>
 	);
 };

From 7560629799a9c43a412d5d0433fefa1ffeaf3284 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Thu, 10 Mar 2022 03:39:02 +0900
Subject: [PATCH 3/5] Clear out margin bottom for help text

---
 packages/components/src/base-control/index.js |  1 +
 .../styles/base-control-styles.js             | 27 ++++++++++++++-----
 2 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/packages/components/src/base-control/index.js b/packages/components/src/base-control/index.js
index 9762a65ad94f7..a8c19457d1364 100644
--- a/packages/components/src/base-control/index.js
+++ b/packages/components/src/base-control/index.js
@@ -83,6 +83,7 @@ function BaseControl( {
 				<StyledHelp
 					id={ id ? id + '__help' : undefined }
 					className="components-base-control__help"
+					__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
 				>
 					{ help }
 				</StyledHelp>
diff --git a/packages/components/src/base-control/styles/base-control-styles.js b/packages/components/src/base-control/styles/base-control-styles.js
index 2c9e7d3ee954c..376585139523e 100644
--- a/packages/components/src/base-control/styles/base-control-styles.js
+++ b/packages/components/src/base-control/styles/base-control-styles.js
@@ -15,16 +15,17 @@ export const Wrapper = styled.div`
 	font-size: ${ font( 'default.fontSize' ) };
 `;
 
-const deprecatedMargin = ( { __nextHasNoMarginBottom = false } ) => {
-	return ! __nextHasNoMarginBottom
-		? css`
-				margin-bottom: ${ space( 2 ) };
-		  `
-		: undefined;
+const deprecatedMarginField = ( { __nextHasNoMarginBottom = false } ) => {
+	return (
+		! __nextHasNoMarginBottom &&
+		css`
+			margin-bottom: ${ space( 2 ) };
+		`
+	);
 };
 
 export const StyledField = styled.div`
-	${ deprecatedMargin }
+	${ deprecatedMarginField }
 
 	.components-panel__row & {
 		margin-bottom: inherit;
@@ -40,11 +41,23 @@ export const StyledLabel = styled.label`
 	${ labelStyles }
 `;
 
+const deprecatedMarginHelp = ( { __nextHasNoMarginBottom = false } ) => {
+	return (
+		! __nextHasNoMarginBottom &&
+		css`
+			margin-bottom: revert;
+		`
+	);
+};
+
 export const StyledHelp = styled.p`
 	margin-top: ${ space( 2 ) };
+	margin-bottom: 0;
 	font-size: ${ font( 'helpText.fontSize' ) };
 	font-style: normal;
 	color: ${ COLORS.mediumGray.text };
+
+	${ deprecatedMarginHelp }
 `;
 
 export const StyledVisualLabel = styled.span`

From dfcaa3088230c9787dbff4020fa8048e408a1e85 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Thu, 10 Mar 2022 03:48:09 +0900
Subject: [PATCH 4/5] Add changelog entry

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

diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
index 69a2735bd44ed..80f5025e28e3e 100644
--- a/packages/components/CHANGELOG.md
+++ b/packages/components/CHANGELOG.md
@@ -6,6 +6,7 @@
 
 -   `ConfirmDialog`: Add support for custom label text on the confirmation and cancelation buttons ([#38994](https://github.com/WordPress/gutenberg/pull/38994))
 -   `InputControl`: Allow `onBlur` for empty values to commit the change when `isPressEnterToChange` is true, and move reset behavior to the ESCAPE key. ([#39109](https://github.com/WordPress/gutenberg/pull/39109)).
+-   `BaseControl`: Add `__nextHasNoMarginBottom` prop for opting into the new margin-free styles ([#39325](https://github.com/WordPress/gutenberg/pull/39325)).
 
 ### Bug Fix
 

From 6d7d2f1e5bf0f851e82241812941aa348cda3f90 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Thu, 10 Mar 2022 23:26:26 +0900
Subject: [PATCH 5/5] Fixup readme

Co-authored-by: Marco Ciampini <marco.ciampo@gmail.com>
---
 packages/components/src/base-control/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/components/src/base-control/README.md b/packages/components/src/base-control/README.md
index dbb3e66b4464b..6e507ee4df87a 100644
--- a/packages/components/src/base-control/README.md
+++ b/packages/components/src/base-control/README.md
@@ -65,12 +65,12 @@ The content to be displayed within the BaseControl.
 
 ### __nextHasNoMarginBottom
 
+Start opting into the new margin-free styles that will become the default in a future version.
+
 -   Type: `Boolean`
 -   Required: No
 -   Default: `false`
 
-Start opting into the new margin-free styles that will become the default in a future version.
-
 ## BaseControl.VisualLabel
 
 `BaseControl.VisualLabel` component is used to render a purely visual label inside a `BaseControl` component.