Dropdown: deprecate position prop, use popoverProps instead (#4…

…6865) * Update types and add deprecation error * Update docs * remove control from Storybook * Cleaner code * Fix Storybook warning * Replace `position` with `popoverProps.placement` across the project * CHANGELOG
WordPress · Jan 12, 2023 · fe7efd6 · fe7efd6 · github-actions · Jan 12, 2023
1 parent e14f3dc
commit fe7efd6
Show file tree

Hide file tree

Showing 20 changed files with 50 additions and 45 deletions.
diff --git a/packages/block-editor/src/components/block-alignment-matrix-control/index.js b/packages/block-editor/src/components/block-alignment-matrix-control/index.js
@@ -23,8 +23,7 @@ function BlockAlignmentMatrixControl( props ) {
 
 	return (
 		<Dropdown
-			position="bottom right"
-			popoverProps={ { variant: 'toolbar' } }
+			popoverProps={ { variant: 'toolbar', placement: 'bottom-start' } }
 			renderToggle={ ( { onToggle, isOpen } ) => {
 				const openOnArrowDown = ( event ) => {
 					if ( ! isOpen && event.keyCode === DOWN ) {

diff --git a/packages/block-editor/src/components/block-navigation/dropdown.js b/packages/block-editor/src/components/block-navigation/dropdown.js
@@ -56,7 +56,7 @@ function BlockNavigationDropdown( { isDisabled, ...props }, ref ) {
 	return (
 		<Dropdown
 			contentClassName="block-editor-block-navigation__popover"
-			position="bottom right"
+			popoverProps={ { placement: 'bottom-start' } }
 			renderToggle={ ( { isOpen, onToggle } ) => (
 				<BlockNavigationDropdownToggle
 					{ ...props }

diff --git a/packages/block-editor/src/components/color-style-selector/index.js b/packages/block-editor/src/components/color-style-selector/index.js
@@ -87,7 +87,7 @@ const BlockColorsStyleSelector = ( { children, ...other } ) => {
 
 	return (
 		<Dropdown
-			position="bottom right"
+			popoverProps={ { placement: 'bottom-start' } }
 			className="block-library-colors-selector"
 			contentClassName="block-library-colors-selector__popover"
 			renderToggle={ renderToggleComponent( other ) }

diff --git a/packages/block-editor/src/components/image-editor/constants.js b/packages/block-editor/src/components/image-editor/constants.js
@@ -1,6 +1,6 @@
 export const MIN_ZOOM = 100;
 export const MAX_ZOOM = 300;
 export const POPOVER_PROPS = {
-	position: 'bottom right',
+	placement: 'bottom-start',
 	variant: 'toolbar',
 };
diff --git a/packages/block-editor/src/components/inserter/index.js b/packages/block-editor/src/components/inserter/index.js
@@ -207,7 +207,7 @@ class Inserter extends Component {
 					'block-editor-inserter__popover',
 					{ 'is-quick': isQuick }
 				) }
-				position={ position }
+				popoverProps={ { position } }
 				onToggle={ this.onToggle }
 				expandOnMobile
 				headerTitle={ __( 'Add a block' ) }

diff --git a/packages/block-editor/src/components/tool-selector/index.js b/packages/block-editor/src/components/tool-selector/index.js
@@ -51,7 +51,7 @@ function ToolSelector( props, ref ) {
 					label={ __( 'Tools' ) }
 				/>
 			) }
-			position="bottom right"
+			popoverProps={ { placement: 'bottom-start' } }
 			renderContent={ () => (
 				<>
 					<NavigableMenu role="menu" aria-label={ __( 'Tools' ) }>

diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Enhancements
+
+-   `Dropdown`: deprecate `position`  prop, use `popoverProps` instead ([46865](https://github.com/WordPress/gutenberg/pull/46865)).
+
 ### Internal
 
 -   `Toolbar`: move all subcomponents under the same folder ([46951](https://github.com/WordPress/gutenberg/pull/46951)).

diff --git a/packages/components/src/dropdown/README.md b/packages/components/src/dropdown/README.md
@@ -13,7 +13,7 @@ const MyDropdown = () => (
 	<Dropdown
 		className="my-container-class-name"
 		contentClassName="my-popover-content-classname"
-		position="bottom right"
+		popoverProps={ { placement: 'bottom-start' } }
 		renderToggle={ ( { isOpen, onToggle } ) => (
 			<Button
 				variant="primary"
@@ -90,13 +90,6 @@ Use this object to access properties/features of the `Popover` component that ar
 
 -   Required: No
 
-### `position`: `PopoverProps[ 'position' ]`
-
-The direction in which the popover should open relative to its parent node. Specify a y- and an x-axis as a space-separated string. Supports `"top"`, `"bottom"` y-axis, and `"left"`, `"center"`, `"right"` x-axis.
-
--   Required: No
--   Default: `"top center"`
-
 ### `renderContent`: `( props: CallbackProps ) => ReactNode`
 
 A callback invoked to render the content of the dropdown menu.

diff --git a/packages/components/src/dropdown/index.tsx b/packages/components/src/dropdown/index.tsx
@@ -9,6 +9,7 @@ import type { ForwardedRef } from 'react';
  */
 import { forwardRef, useEffect, useRef, useState } from '@wordpress/element';
 import { useMergeRefs } from '@wordpress/compose';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
@@ -41,14 +42,24 @@ function UnforwardedDropdown(
 		expandOnMobile,
 		headerTitle,
 		focusOnMount,
-		position,
 		popoverProps,
 		onClose,
 		onToggle,
 		style,
+
+		// Deprecated props
+		position,
 	}: DropdownProps,
 	forwardedRef: ForwardedRef< any >
 ) {
+	if ( position !== undefined ) {
+		deprecated( '`position` prop in wp.components.Dropdown', {
+			since: '6.2',
+			alternative: '`popoverProps.placement` prop',
+			hint: 'Note that the `position` prop will override any values passed through the `popoverProps.placement` prop.',
+		} );
+	}
+
 	// Use internal state instead of a ref to make sure that the component
 	// re-renders when the popover's anchor updates.
 	const [ fallbackPopoverAnchor, setFallbackPopoverAnchor ] =
@@ -141,7 +152,7 @@ function UnforwardedDropdown(
 					{ ...popoverProps }
 					className={ classnames(
 						'components-dropdown__content',
-						popoverProps ? popoverProps.className : undefined,
+						popoverProps?.className,
 						contentClassName
 					) }
 				>
@@ -161,18 +172,18 @@ function UnforwardedDropdown(
  * const MyDropdown = () => (
  *   <Dropdown
  *     className="my-container-class-name"
- *     contentClassName="my-popover-content-classname"
- *     position="bottom right"
+ *     contentClassName="my-dropdown-content-classname"
+ *     popoverProps={ { placement: 'bottom-start' } }
  *     renderToggle={ ( { isOpen, onToggle } ) => (
  *       <Button
  *         variant="primary"
  *         onClick={ onToggle }
  *         aria-expanded={ isOpen }
  *       >
- *         Toggle Popover!
+ *         Toggle Dropdown!
  *       </Button>
  *     ) }
- *     renderContent={ () => <div>This is the content of the popover.</div> }
+ *     renderContent={ () => <div>This is the content of the dropdown.</div> }
  *   />
  * );
  * ```

diff --git a/packages/components/src/dropdown/stories/index.tsx b/packages/components/src/dropdown/stories/index.tsx
@@ -16,11 +16,12 @@ const meta: ComponentMeta< typeof Dropdown > = {
 	subcomponents: { DropdownContentWrapper },
 	argTypes: {
 		focusOnMount: {
+			options: [ 'firstElement', true, false ],
 			control: {
 				type: 'radio',
-				options: [ 'firstElement', true, false ],
 			},
 		},
+		position: { control: { type: null } },
 		renderContent: { control: { type: null } },
 		renderToggle: { control: { type: null } },
 	},
@@ -42,7 +43,6 @@ const Template: ComponentStory< typeof Dropdown > = ( args ) => {
 
 export const Default: ComponentStory< typeof Dropdown > = Template.bind( {} );
 Default.args = {
-	position: 'bottom right',
 	renderToggle: ( { isOpen, onToggle } ) => (
 		<Button onClick={ onToggle } aria-expanded={ isOpen } isPrimary>
 			Open dropdown

diff --git a/packages/components/src/dropdown/types.ts b/packages/components/src/dropdown/types.ts
@@ -81,16 +81,6 @@ export type DropdownProps = {
 		ComponentPropsWithoutRef< typeof Popover >,
 		'children'
 	>;
-	/**
-	 * The direction in which the popover should open
-	 * relative to its parent node.
-	 * Specify a y- and an x-axis as a space-separated string.
-	 * Supports "top", "bottom" y-axis,
-	 * and "left", "center", "right" x-axis.
-	 *
-	 * @default 'top center'
-	 */
-	position?: PopoverProps[ 'position' ];
 	/**
 	 * A callback invoked to render the content of the dropdown menu.
 	 * Its first argument is the same as the renderToggle prop.
@@ -112,4 +102,13 @@ export type DropdownProps = {
 	 * The style of the global container.
 	 */
 	style?: CSSProperties;
+	/**
+	 * Legacy way to specify the popover's position with respect to its anchor.
+	 * For details about the possible values, see the `Popover` component's docs.
+	 * _Note: this prop is deprecated. Use the `popoverProps.placement` prop
+	 * instead._
+	 *
+	 * @deprecated
+	 */
+	position?: PopoverProps[ 'position' ];
 };
diff --git a/packages/edit-post/src/components/header/template-title/index.js b/packages/edit-post/src/components/header/template-title/index.js
@@ -77,7 +77,7 @@ function TemplateTitle() {
 			</Button>
 			{ hasOptions ? (
 				<Dropdown
-					position="bottom center"
+					popoverProps={ { placement: 'bottom' } }
 					contentClassName="edit-post-template-top-area__popover"
 					renderToggle={ ( { onToggle } ) => (
 						<Button

diff --git a/packages/edit-post/src/components/sidebar/post-schedule/index.js b/packages/edit-post/src/components/sidebar/post-schedule/index.js
@@ -16,7 +16,7 @@ export default function PostSchedule() {
 	const [ popoverAnchor, setPopoverAnchor ] = useState( null );
 	// Memoize popoverProps to avoid returning a new object every time.
 	const popoverProps = useMemo(
-		() => ( { anchor: popoverAnchor } ),
+		() => ( { anchor: popoverAnchor, placement: 'bottom-end' } ),
 		[ popoverAnchor ]
 	);
 
@@ -29,7 +29,6 @@ export default function PostSchedule() {
 				<span>{ __( 'Publish' ) }</span>
 				<Dropdown
 					popoverProps={ popoverProps }
-					position="bottom left"
 					contentClassName="edit-post-post-schedule__dialog"
 					focusOnMount
 					renderToggle={ ( { isOpen, onToggle } ) => (

diff --git a/packages/edit-post/src/components/sidebar/post-template/index.js b/packages/edit-post/src/components/sidebar/post-template/index.js
@@ -20,7 +20,7 @@ export default function PostTemplate() {
 	const [ popoverAnchor, setPopoverAnchor ] = useState( null );
 	// Memoize popoverProps to avoid returning a new object every time.
 	const popoverProps = useMemo(
-		() => ( { anchor: popoverAnchor } ),
+		() => ( { anchor: popoverAnchor, placement: 'bottom-end' } ),
 		[ popoverAnchor ]
 	);
 
@@ -57,7 +57,6 @@ export default function PostTemplate() {
 			<span>{ __( 'Template' ) }</span>
 			<Dropdown
 				popoverProps={ popoverProps }
-				position="bottom left"
 				className="edit-post-post-template__dropdown"
 				contentClassName="edit-post-post-template__dialog"
 				focusOnMount

diff --git a/packages/edit-post/src/components/sidebar/post-url/index.js b/packages/edit-post/src/components/sidebar/post-url/index.js
@@ -16,7 +16,7 @@ export default function PostURL() {
 	const [ popoverAnchor, setPopoverAnchor ] = useState( null );
 	// Memoize popoverProps to avoid returning a new object every time.
 	const popoverProps = useMemo(
-		() => ( { anchor: popoverAnchor } ),
+		() => ( { anchor: popoverAnchor, placement: 'bottom-end' } ),
 		[ popoverAnchor ]
 	);
 
@@ -26,7 +26,6 @@ export default function PostURL() {
 				<span>{ __( 'URL' ) }</span>
 				<Dropdown
 					popoverProps={ popoverProps }
-					position="bottom left"
 					className="edit-post-post-url__dropdown"
 					contentClassName="edit-post-post-url__dialog"
 					focusOnMount

diff --git a/packages/edit-post/src/components/sidebar/post-visibility/index.js b/packages/edit-post/src/components/sidebar/post-visibility/index.js
@@ -21,6 +21,7 @@ export function PostVisibility() {
 			// Anchor the popover to the middle of the entire row so that it doesn't
 			// move around when the label changes.
 			anchor: popoverAnchor,
+			placement: 'bottom-end',
 		} ),
 		[ popoverAnchor ]
 	);
@@ -40,7 +41,6 @@ export function PostVisibility() {
 					) }
 					{ canEdit && (
 						<Dropdown
-							position="bottom left"
 							contentClassName="edit-post-post-visibility__dialog"
 							popoverProps={ popoverProps }
 							focusOnMount

diff --git a/packages/edit-site/src/components/header-edit-mode/document-actions/index.js b/packages/edit-site/src/components/header-edit-mode/document-actions/index.js
@@ -88,6 +88,7 @@ export default function DocumentActions() {
 			// Use the title wrapper as the popover anchor so that the dropdown is
 			// centered over the whole title area rather than just one part of it.
 			anchor: popoverAnchor,
+			placement: 'bottom',
 		} ),
 		[ popoverAnchor ]
 	);
@@ -146,7 +147,6 @@ export default function DocumentActions() {
 
 				<Dropdown
 					popoverProps={ popoverProps }
-					position="bottom center"
 					renderToggle={ ( { isOpen, onToggle } ) => (
 						<Button
 							className="edit-site-document-actions__get-info"

diff --git a/packages/editor/src/components/table-of-contents/index.js b/packages/editor/src/components/table-of-contents/index.js
@@ -23,7 +23,9 @@ function TableOfContents(
 	);
 	return (
 		<Dropdown
-			position={ repositionDropdown ? 'middle right right' : 'bottom' }
+			popoverProps={ {
+				placement: repositionDropdown ? 'right' : 'bottom',
+			} }
 			className="table-of-contents"
 			contentClassName="table-of-contents__popover"
 			renderToggle={ ( { isOpen, onToggle } ) => (

diff --git a/packages/interface/src/components/more-menu-dropdown/index.js b/packages/interface/src/components/more-menu-dropdown/index.js
@@ -28,7 +28,7 @@ export default function MoreMenuDropdown( {
 			icon={ moreVertical }
 			label={ label }
 			popoverProps={ {
-				position: 'bottom left',
+				placement: 'bottom-end',
 				...popoverProps,
 				className: classnames(
 					'interface-more-menu-dropdown__content',

diff --git a/packages/list-reusable-blocks/src/components/import-dropdown/index.js b/packages/list-reusable-blocks/src/components/import-dropdown/index.js
@@ -13,7 +13,7 @@ import ImportForm from '../import-form';
 function ImportDropdown( { onUpload } ) {
 	return (
 		<Dropdown
-			position="bottom right"
+			popoverProps={ { placement: 'bottom-start' } }
 			contentClassName="list-reusable-blocks-import-dropdown__content"
 			renderToggle={ ( { isOpen, onToggle } ) => (
 				<Button