Deprecate bottom margin on BaseControl-based components (#64408)

* BaseControl: Deprecate bottom margin * Propagate to components * Missed spots * Add changelog * List all affected components in changelog Co-authored-by: mirka <[email protected]> Co-authored-by: tyxla <[email protected]>
WordPress · Aug 13, 2024 · 46f9fe0 · 46f9fe0
1 parent 898f597
commit 46f9fe0
Show file tree

Hide file tree

Showing 38 changed files with 191 additions and 75 deletions.
diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+### Deprecations
+
+-   Deprecate bottom margin on the following `BaseControl`-based components. Set the `__nextHasNoMarginBottom` prop to true to start opting into the new styles, which will become the default in a future version ([#64408](https://github.com/WordPress/gutenberg/pull/64408)).
+    -   `BaseControl`
+    -   `CheckboxControl`
+    -   `ComboboxControl`
+    -   `DimensionControl`
+    -   `FocalPointPicker`
+    -   `RangeControl`
+    -   `SearchControl`
+    -   `SelectControl`
+    -   `TextControl`
+    -   `TextareaControl`
+    -   `ToggleControl`
+    -   `ToggleGroupControl`
+    -   `TreeSelect`
+
 ### New Features
 
 -   `Composite`: add stable version of the component ([#63564](https://github.com/WordPress/gutenberg/pull/63564)).

diff --git a/packages/components/src/base-control/index.tsx b/packages/components/src/base-control/index.tsx
@@ -7,6 +7,7 @@ import type { ForwardedRef } from 'react';
 /**
  * WordPress dependencies
  */
+import deprecated from '@wordpress/deprecated';
 import { forwardRef } from '@wordpress/element';
 
 /**
@@ -31,6 +32,7 @@ const UnconnectedBaseControl = (
 ) => {
 	const {
 		__nextHasNoMarginBottom = false,
+		__associatedWPComponentName = 'BaseControl',
 		id,
 		label,
 		hideLabelFromVision = false,
@@ -39,6 +41,17 @@ const UnconnectedBaseControl = (
 		children,
 	} = useContextSystem( props, 'BaseControl' );
 
+	if ( ! __nextHasNoMarginBottom ) {
+		deprecated(
+			`Bottom margin styles for wp.components.${ __associatedWPComponentName }`,
+			{
+				since: '6.7',
+				version: '7.0',
+				hint: 'Set the `__nextHasNoMarginBottom` prop to true to start opting into the new styles, which will become the default in a future version.',
+			}
+		);
+	}
+
 	return (
 		<Wrapper className={ className }>
 			<StyledField

diff --git a/packages/components/src/base-control/types.ts b/packages/components/src/base-control/types.ts
@@ -10,6 +10,13 @@ export type BaseControlProps = {
 	 * @default false
 	 */
 	__nextHasNoMarginBottom?: boolean;
+	/**
+	 * Temporary private prop for showing better deprecation messages,
+	 * e.g. `Some feature from wp.components.${ __associatedWPControl } is deprecated`.
+	 *
+	 * @ignore
+	 */
+	__associatedWPComponentName?: string;
 	/**
 	 * The HTML `id` of the control element (passed in as a child to `BaseControl`) to which labels and help text are being generated.
 	 * This is necessary to accessibly associate the label with that element.

diff --git a/packages/components/src/checkbox-control/index.tsx b/packages/components/src/checkbox-control/index.tsx
@@ -95,6 +95,7 @@ export function CheckboxControl(
 	return (
 		<BaseControl
 			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+			__associatedWPComponentName="CheckboxControl"
 			label={ heading }
 			id={ id }
 			help={

diff --git a/packages/components/src/checkbox-control/stories/index.story.tsx b/packages/components/src/checkbox-control/stories/index.story.tsx
@@ -59,6 +59,7 @@ export const Default: StoryFn< typeof CheckboxControl > = DefaultTemplate.bind(
 	{}
 );
 Default.args = {
+	__nextHasNoMarginBottom: true,
 	label: 'Is author',
 	help: 'Is the user an author or not?',
 };

diff --git a/packages/components/src/checkbox-control/test/index.tsx b/packages/components/src/checkbox-control/test/index.tsx
@@ -20,13 +20,20 @@ const noop = () => {};
 const getInput = () => screen.getByRole( 'checkbox' ) as HTMLInputElement;
 
 const CheckboxControl = ( props: Omit< CheckboxControlProps, 'onChange' > ) => {
-	return <BaseCheckboxControl onChange={ noop } { ...props } />;
+	return (
+		<BaseCheckboxControl
+			onChange={ noop }
+			{ ...props }
+			__nextHasNoMarginBottom
+		/>
+	);
 };
 
 const ControlledCheckboxControl = ( { onChange }: CheckboxControlProps ) => {
 	const [ isChecked, setChecked ] = useState( false );
 	return (
 		<BaseCheckboxControl
+			__nextHasNoMarginBottom
 			checked={ isChecked }
 			onChange={ ( value ) => {
 				setChecked( value );

diff --git a/packages/components/src/combobox-control/index.tsx b/packages/components/src/combobox-control/index.tsx
@@ -320,6 +320,7 @@ function ComboboxControl( props: ComboboxControlProps ) {
 		<DetectOutside onFocusOutside={ onFocusOutside }>
 			<BaseControl
 				__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+				__associatedWPComponentName="ComboboxControl"
 				className={ clsx( className, 'components-combobox-control' ) }
 				label={ label }
 				id={ `components-form-token-input-${ instanceId }` }

diff --git a/packages/components/src/combobox-control/stories/index.story.tsx b/packages/components/src/combobox-control/stories/index.story.tsx
@@ -76,6 +76,7 @@ const Template: StoryFn< typeof ComboboxControl > = ( {
 };
 export const Default = Template.bind( {} );
 Default.args = {
+	__nextHasNoMarginBottom: true,
 	allowReset: false,
 	label: 'Select a country',
 	options: countryOptions,
@@ -135,8 +136,7 @@ const optionsWithDisabledOptions = countryOptions.map( ( option, index ) => ( {
 } ) );
 
 WithDisabledOptions.args = {
-	allowReset: false,
-	label: 'Select a country',
+	...Default.args,
 	options: optionsWithDisabledOptions,
 };
 
@@ -148,8 +148,7 @@ WithDisabledOptions.args = {
 export const NotExpandOnFocus = Template.bind( {} );
 
 NotExpandOnFocus.args = {
-	allowReset: false,
-	label: 'Select a country',
+	...Default.args,
 	options: countryOptions,
 	expandOnFocus: false,
 };
diff --git a/packages/components/src/combobox-control/test/index.tsx b/packages/components/src/combobox-control/test/index.tsx
@@ -12,7 +12,7 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import ComboboxControl from '..';
+import _ComboboxControl from '..';
 import type { ComboboxControlOption, ComboboxControlProps } from '../types';
 
 const timezones = [
@@ -57,6 +57,10 @@ const getAllOptions = () => screen.getAllByRole( 'option' );
 const getOptionSearchString = ( option: ComboboxControlOption ) =>
 	option.label.substring( 0, 11 );
 
+const ComboboxControl = ( props: ComboboxControlProps ) => {
+	return <_ComboboxControl { ...props } __nextHasNoMarginBottom />;
+};
+
 const ControlledComboboxControl = ( {
 	value: valueProp,
 	onChange,

diff --git a/packages/components/src/dimension-control/index.tsx b/packages/components/src/dimension-control/index.tsx
@@ -16,6 +16,15 @@ import SelectControl from '../select-control';
 import sizesTable, { findSizeBySlug } from './sizes';
 import type { DimensionControlProps, Size } from './types';
 import type { SelectControlSingleSelectionProps } from '../select-control/types';
+import { ContextSystemProvider } from '../context';
+
+const CONTEXT_VALUE = {
+	BaseControl: {
+		// Temporary during deprecation grace period: Overrides the underlying `__associatedWPComponentName`
+		// via the context system to override the value set by SelectControl.
+		_overrides: { __associatedWPComponentName: 'DimensionControl' },
+	},
+};
 
 /**
  * `DimensionControl` is a component designed to provide a UI to control spacing and/or dimensions.
@@ -87,16 +96,21 @@ export function DimensionControl( props: DimensionControlProps ) {
 	);
 
 	return (
-		<SelectControl
-			__next40pxDefaultSize={ __next40pxDefaultSize }
-			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
-			className={ clsx( className, 'block-editor-dimension-control' ) }
-			label={ selectLabel }
-			hideLabelFromVision={ false }
-			value={ value }
-			onChange={ onChangeSpacingSize }
-			options={ formatSizesAsOptions( sizes ) }
-		/>
+		<ContextSystemProvider value={ CONTEXT_VALUE }>
+			<SelectControl
+				__next40pxDefaultSize={ __next40pxDefaultSize }
+				__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+				className={ clsx(
+					className,
+					'block-editor-dimension-control'
+				) }
+				label={ selectLabel }
+				hideLabelFromVision={ false }
+				value={ value }
+				onChange={ onChangeSpacingSize }
+				options={ formatSizesAsOptions( sizes ) }
+			/>
+		</ContextSystemProvider>
 	);
 }
 

diff --git a/packages/components/src/dimension-control/stories/index.story.tsx b/packages/components/src/dimension-control/stories/index.story.tsx
@@ -44,6 +44,7 @@ const Template: StoryFn< typeof DimensionControl > = ( args ) => (
 export const Default = Template.bind( {} );
 
 Default.args = {
+	__nextHasNoMarginBottom: true,
 	label: 'Please select a size',
 	sizes,
 };
diff --git a/packages/components/src/dimension-control/test/__snapshots__/index.test.js.snap b/packages/components/src/dimension-control/test/__snapshots__/index.test.js.snap
@@ -13,10 +13,6 @@ exports[`DimensionControl rendering renders with custom sizes 1`] = `
   box-sizing: inherit;
 }
 
-.emotion-2 {
-  margin-bottom: calc(4px * 2);
-}
-
 .components-panel__row .emotion-2 {
   margin-bottom: inherit;
 }
@@ -299,10 +295,6 @@ exports[`DimensionControl rendering renders with defaults 1`] = `
   box-sizing: inherit;
 }
 
-.emotion-2 {
-  margin-bottom: calc(4px * 2);
-}
-
 .components-panel__row .emotion-2 {
   margin-bottom: inherit;
 }
@@ -595,10 +587,6 @@ exports[`DimensionControl rendering renders with icon and custom icon label 1`]
   box-sizing: inherit;
 }
 
-.emotion-2 {
-  margin-bottom: calc(4px * 2);
-}
-
 .components-panel__row .emotion-2 {
   margin-bottom: inherit;
 }
@@ -903,10 +891,6 @@ exports[`DimensionControl rendering renders with icon and default icon label 1`]
   box-sizing: inherit;
 }
 
-.emotion-2 {
-  margin-bottom: calc(4px * 2);
-}
-
 .components-panel__row .emotion-2 {
   margin-bottom: inherit;
 }

diff --git a/packages/components/src/dimension-control/test/index.test.js b/packages/components/src/dimension-control/test/index.test.js
@@ -12,7 +12,11 @@ import { plus } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
-import { DimensionControl } from '../';
+import { DimensionControl as _DimensionControl } from '../';
+
+const DimensionControl = ( props ) => {
+	return <_DimensionControl { ...props } __nextHasNoMarginBottom />;
+};
 
 describe( 'DimensionControl', () => {
 	const onChangeHandler = jest.fn();

diff --git a/packages/components/src/focal-point-picker/index.tsx b/packages/components/src/focal-point-picker/index.tsx
@@ -251,6 +251,7 @@ export function FocalPointPicker( {
 		<BaseControl
 			{ ...restProps }
 			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+			__associatedWPComponentName="FocalPointPicker"
 			label={ label }
 			id={ id }
 			help={ help }

diff --git a/packages/components/src/focal-point-picker/stories/index.story.tsx b/packages/components/src/focal-point-picker/stories/index.story.tsx
@@ -49,6 +49,9 @@ const Template: StoryFn< typeof FocalPointPicker > = ( {
 };
 
 export const Default = Template.bind( {} );
+Default.args = {
+	__nextHasNoMarginBottom: true,
+};
 
 export const Image = Template.bind( {} );
 Image.args = {

diff --git a/packages/components/src/focal-point-picker/test/index.tsx b/packages/components/src/focal-point-picker/test/index.tsx
@@ -7,12 +7,16 @@ import userEvent from '@testing-library/user-event';
 /**
  * Internal dependencies
  */
-import Picker from '..';
+import _Picker from '..';
 import type { FocalPointPickerProps } from '../types';
 
 type Log = { name: string; args: unknown[] };
 type EventLogger = ( name: string, args: unknown[] ) => void;
 
+const Picker = ( props: React.ComponentProps< typeof _Picker > ) => {
+	return <_Picker { ...props } __nextHasNoMarginBottom />;
+};
+
 const props: FocalPointPickerProps = {
 	onChange: jest.fn(),
 	url: 'test-url',

diff --git a/packages/components/src/range-control/index.tsx b/packages/components/src/range-control/index.tsx
@@ -213,6 +213,7 @@ function UnforwardedRangeControl(
 	return (
 		<BaseControl
 			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+			__associatedWPComponentName="RangeControl"
 			className={ classes }
 			label={ label }
 			hideLabelFromVision={ hideLabelFromVision }

diff --git a/packages/components/src/range-control/stories/index.story.tsx b/packages/components/src/range-control/stories/index.story.tsx
@@ -70,6 +70,7 @@ const Template: StoryFn< typeof RangeControl > = ( { onChange, ...args } ) => {
 
 export const Default: StoryFn< typeof RangeControl > = Template.bind( {} );
 Default.args = {
+	__nextHasNoMarginBottom: true,
 	help: 'Please select how transparent you would like this.',
 	initialPosition: 50,
 	label: 'Opacity',
@@ -104,6 +105,7 @@ export const WithAnyStep: StoryFn< typeof RangeControl > = ( {
 	);
 };
 WithAnyStep.args = {
+	__nextHasNoMarginBottom: true,
 	label: 'Brightness',
 	step: 'any',
 };
@@ -167,6 +169,7 @@ export const WithIntegerStepAndMarks: StoryFn< typeof RangeControl > =
 	MarkTemplate.bind( {} );
 
 WithIntegerStepAndMarks.args = {
+	__nextHasNoMarginBottom: true,
 	label: 'Integer Step',
 	marks: marksBase,
 	max: 10,
@@ -183,6 +186,7 @@ export const WithDecimalStepAndMarks: StoryFn< typeof RangeControl > =
 	MarkTemplate.bind( {} );
 
 WithDecimalStepAndMarks.args = {
+	__nextHasNoMarginBottom: true,
 	marks: [
 		...marksBase,
 		{ value: 3.5, label: '3.5' },
@@ -202,6 +206,7 @@ export const WithNegativeMinimumAndMarks: StoryFn< typeof RangeControl > =
 	MarkTemplate.bind( {} );
 
 WithNegativeMinimumAndMarks.args = {
+	__nextHasNoMarginBottom: true,
 	marks: marksWithNegatives,
 	max: 10,
 	min: -10,
@@ -217,6 +222,7 @@ export const WithNegativeRangeAndMarks: StoryFn< typeof RangeControl > =
 	MarkTemplate.bind( {} );
 
 WithNegativeRangeAndMarks.args = {
+	__nextHasNoMarginBottom: true,
 	marks: marksWithNegatives,
 	max: -1,
 	min: -10,
@@ -232,6 +238,7 @@ export const WithAnyStepAndMarks: StoryFn< typeof RangeControl > =
 	MarkTemplate.bind( {} );
 
 WithAnyStepAndMarks.args = {
+	__nextHasNoMarginBottom: true,
 	marks: marksBase,
 	max: 10,
 	min: 0,