@wordpress/components 19.15.0 → 20.0.0

package/src/divider/README.md

@@ -32,19 +32,26 @@ function Example() {
 
 Adjusts all margins on the inline dimension.
 
-- Required: No
+-   Required: No
+
+### `marginEnd`: `number`
+
+Adjusts the inline-end margin.
+
+-   Required: No
 
 ### `marginStart`: `number`
 
 Adjusts the inline-start margin.
 
-- Required: No
+-   Required: No
 
-### `marginEnd`: `number`
+### `orientation`: `horizontal | vertical`
 
-Adjusts the inline-end margin.
+Divider's orientation. When using inside a flex container, you may need to make sure the divider is `stretch` aligned in order for it to be visible.
 
-- Required: No
+-   Required: No
+-   Default: `horizontal`
 
 ### Inherited props
 

package/src/divider/component.tsx

@@ -14,10 +14,10 @@ import {
 	WordPressComponentProps,
 } from '../ui/context';
 import { DividerView } from './styles';
-import type { Props } from './types';
+import type { DividerProps } from './types';
 
 function UnconnectedDivider(
-	props: WordPressComponentProps< Props, 'hr', false >,
+	props: WordPressComponentProps< DividerProps, 'hr', false >,
 	forwardedRef: ForwardedRef< any >
 ) {
 	const contextProps = useContextSystem( props, 'Divider' );
@@ -34,7 +34,6 @@ function UnconnectedDivider(
 /**
  * `Divider` is a layout component that separates groups of related content.
  *
- * @example
  * ```js
  * import {
  * 		__experimentalDivider as Divider,

package/src/divider/index.ts

@@ -1,2 +1,2 @@
 export { default as Divider } from './component';
-export type { Props as DividerProps } from './types';
+export type { DividerProps } from './types';

package/src/divider/stories/index.tsx

@@ -15,13 +15,13 @@ const meta: ComponentMeta< typeof Divider > = {
 	title: 'Components (Experimental)/Divider',
 	argTypes: {
 		margin: {
-			control: { type: 'number' },
+			control: { type: 'text' },
 		},
 		marginStart: {
-			control: { type: 'number' },
+			control: { type: 'text' },
 		},
 		marginEnd: {
-			control: { type: 'number' },
+			control: { type: 'text' },
 		},
 	},
 	parameters: {
@@ -41,7 +41,7 @@ const Template: ComponentStory< typeof Divider > = ( args ) => (
 
 export const Horizontal: ComponentStory< typeof Divider > = Template.bind( {} );
 Horizontal.args = {
-	margin: 2,
+	margin: '2',
 };
 
 export const Vertical: ComponentStory< typeof Divider > = Template.bind( {} );

package/src/divider/styles.ts

@@ -9,10 +9,10 @@ import { css } from '@emotion/react';
  */
 import { space } from '../ui/utils/space';
 import { rtl } from '../utils';
-import type { Props } from './types';
+import type { DividerProps } from './types';
 
 const MARGIN_DIRECTIONS: Record<
-	NonNullable< Props[ 'orientation' ] >,
+	NonNullable< DividerProps[ 'orientation' ] >,
 	Record< 'start' | 'end', string >
 > = {
 	vertical: {
@@ -33,7 +33,7 @@ const renderMargin = ( {
 	margin,
 	marginStart,
 	marginEnd,
-}: Props ) =>
+}: DividerProps ) =>
 	css(
 		rtl( {
 			[ MARGIN_DIRECTIONS[ orientation ].start ]: space(
@@ -47,7 +47,7 @@ const renderMargin = ( {
 
 const renderDisplay = ( {
 	'aria-orientation': orientation = 'horizontal',
-}: Props ) => {
+}: DividerProps ) => {
 	return orientation === 'vertical'
 		? css( { display: 'inline' } )
 		: undefined;
@@ -55,7 +55,7 @@ const renderDisplay = ( {
 
 const renderBorder = ( {
 	'aria-orientation': orientation = 'horizontal',
-}: Props ) => {
+}: DividerProps ) => {
 	return css( {
 		[ orientation === 'vertical' ? 'borderRight' : 'borderBottom' ]:
 			'1px solid currentColor',
@@ -64,13 +64,13 @@ const renderBorder = ( {
 
 const renderSize = ( {
 	'aria-orientation': orientation = 'horizontal',
-}: Props ) =>
+}: DividerProps ) =>
 	css( {
 		height: orientation === 'vertical' ? 'auto' : 0,
 		width: orientation === 'vertical' ? 0 : 'auto',
 	} );
 
-export const DividerView = styled.hr< Props >`
+export const DividerView = styled.hr< DividerProps >`
 	border: 0;
 	margin: 0;
 

package/src/divider/test/__snapshots__/{index.js.snap → index.tsx.snap}

@@ -23,14 +23,14 @@ Snapshot Diff:
 - Received styles
 + Base styles
 
-@@ -2,10 +2,8 @@
+@@ -2,8 +2,10 @@
     Object {
       "border": "0",
       "border-bottom": "1px solid currentColor",
       "height": "0",
       "margin": "0",
--     "margin-bottom": "calc(4px * 7)",
--     "margin-top": "calc(4px * 7)",
++     "margin-bottom": "calc(4px * 7)",
++     "margin-top": "calc(4px * 7)",
       "width": "auto",
     },
   ]
@@ -41,13 +41,13 @@ Snapshot Diff:
 - Received styles
 + Base styles
 
-@@ -2,9 +2,8 @@
+@@ -2,8 +2,9 @@
     Object {
       "border": "0",
       "border-bottom": "1px solid currentColor",
       "height": "0",
       "margin": "0",
--     "margin-bottom": "calc(4px * 5)",
++     "margin-bottom": "calc(4px * 5)",
       "width": "auto",
     },
   ]
@@ -58,13 +58,13 @@ Snapshot Diff:
 - Received styles
 + Base styles
 
-@@ -2,9 +2,8 @@
+@@ -2,8 +2,9 @@
     Object {
       "border": "0",
       "border-bottom": "1px solid currentColor",
       "height": "0",
       "margin": "0",
--     "margin-top": "calc(4px * 5)",
++     "margin-top": "calc(4px * 5)",
       "width": "auto",
     },
   ]

package/src/divider/test/index.tsx

@@ -0,0 +1,40 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { Divider } from '..';
+
+describe( 'props', () => {
+	beforeEach( () => {
+		render( <Divider /> );
+	} );
+
+	test( 'should render correctly', () => {
+		expect( screen.getByRole( 'separator' ) ).toMatchSnapshot();
+	} );
+
+	test( 'should render marginStart', () => {
+		render( <Divider marginStart={ 5 } /> );
+
+		const dividers = screen.getAllByRole( 'separator' );
+		expect( dividers[ 0 ] ).toMatchStyleDiffSnapshot( dividers[ 1 ] );
+	} );
+
+	test( 'should render marginEnd', () => {
+		render( <Divider marginEnd={ 5 } /> );
+
+		const dividers = screen.getAllByRole( 'separator' );
+		expect( dividers[ 0 ] ).toMatchStyleDiffSnapshot( dividers[ 1 ] );
+	} );
+
+	test( 'should render margin', () => {
+		render( <Divider margin={ 7 } /> );
+
+		const dividers = screen.getAllByRole( 'separator' );
+		expect( dividers[ 0 ] ).toMatchStyleDiffSnapshot( dividers[ 1 ] );
+	} );
+} );

package/src/divider/types.ts

@@ -9,31 +9,37 @@ import type { SeparatorProps } from 'reakit';
  */
 import type { SpaceInput } from '../ui/utils/space';
 
-export interface OwnProps {
+export type DividerProps = Omit<
+	SeparatorProps,
+	'children' | 'unstable_system' | 'orientation'
+> & {
 	/**
 	 * Adjusts all margins on the inline dimension.
+	 *
+	 * Can either be a number (which will act as a multiplier to the library's grid system base of 4px),
+	 * or a literal CSS value string.
 	 */
 	margin?: SpaceInput;
-	/**
-	 * Adjusts the inline-start margin.
-	 */
-	marginStart?: SpaceInput;
 	/**
 	 * Adjusts the inline-end margin.
+	 *
+	 * Can either be a number (which will act as a multiplier to the library's grid system base of 4px),
+	 * or a literal CSS value string.
 	 */
 	marginEnd?: SpaceInput;
 	/**
-	 * Divider's orientation. When using inside a flex container, you may need to make sure the divider is `stretch` aligned
-	 * in order for it to be visible.
+	 * Adjusts the inline-start margin.
+	 *
+	 * Can either be a number (which will act as a multiplier to the library's grid system base of 4px),
+	 * or a literal CSS value string.
+	 */
+	marginStart?: SpaceInput;
+	/**
+	 * Divider's orientation. When using inside a flex container, you may need
+	 * to make sure the divider is `stretch` aligned in order for it to be
+	 * visible.
 	 *
 	 * @default 'horizontal'
 	 */
 	orientation?: SeparatorProps[ 'orientation' ];
-}
-
-export interface Props
-	extends Omit<
-			SeparatorProps,
-			'children' | 'unstable_system' | 'orientation'
-		>,
-		OwnProps {}
+};

package/src/draggable/README.md

@@ -1,6 +1,6 @@
 # Draggable
 
-`Draggable` is a Component that provides a way to set up a a cross-browser (including IE) customisable drag image and the transfer data for the drag event. It decouples the drag handle and the element to drag: use it by wrapping the component that will become the drag handle and providing the DOM ID of the element to drag.
+`Draggable` is a Component that provides a way to set up a cross-browser (including IE) customisable drag image and the transfer data for the drag event. It decouples the drag handle and the element to drag: use it by wrapping the component that will become the drag handle and providing the DOM ID of the element to drag.
 
 Note that the drag handle needs to declare the `draggable="true"` property and bind the `Draggable`s `onDraggableStart` and `onDraggableEnd` event handlers to its own `onDragStart` and `onDragEnd` respectively. `Draggable` takes care of the logic to setup the drag image and the transfer data, but is not concerned with creating an actual DOM element that is draggable.
 

package/src/drop-zone/index.js

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { includes } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -60,12 +59,12 @@ export default function DropZoneComponent( {
 			 * From Windows Chrome 96, the `event.dataTransfer` returns both file object and HTML.
 			 * The order of the checks is important to recognise the HTML drop.
 			 */
-			if ( includes( event.dataTransfer.types, 'text/html' ) ) {
+			if ( event.dataTransfer.types.includes( 'text/html' ) ) {
 				_type = 'html';
 			} else if (
 				// Check for the types because sometimes the files themselves
 				// are only available on drop.
-				includes( event.dataTransfer.types, 'Files' ) ||
+				event.dataTransfer.types.includes( 'Files' ) ||
 				getFilesFromDataTransfer( event.dataTransfer ).length > 0
 			) {
 				_type = 'file';

package/src/dropdown/dropdown-content-wrapper.tsx

@@ -0,0 +1,59 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import {
+	WordPressComponentProps,
+	contextConnect,
+	useContextSystem,
+} from '../ui/context';
+import { DropdownContentWrapperDiv } from './styles';
+import type { DropdownContentWrapperProps } from './types';
+
+function UnconnectedDropdownContentWrapper(
+	props: WordPressComponentProps< DropdownContentWrapperProps, 'div', false >,
+	forwardedRef: ForwardedRef< any >
+) {
+	const { paddingSize = 'small', ...derivedProps } = useContextSystem(
+		props,
+		'DropdownContentWrapper'
+	);
+
+	return (
+		<DropdownContentWrapperDiv
+			{ ...derivedProps }
+			paddingSize={ paddingSize }
+			ref={ forwardedRef }
+		/>
+	);
+}
+
+/**
+ * A convenience wrapper for the `renderContent` when you want to apply
+ * different padding. (Default is `paddingSize="small"`).
+ *
+ * ```jsx
+ * import {
+ *   Dropdown,
+ *   __experimentalDropdownContentWrapper as DropdownContentWrapper,
+ * } from '@wordpress/components';
+ *
+ * <Dropdown
+ *   renderContent={ () => (
+ *     <DropdownContentWrapper paddingSize="medium">
+ *       My dropdown content
+ *     </DropdownContentWrapper>
+ * ) }
+ * />
+ * ```
+ */
+export const DropdownContentWrapper = contextConnect(
+	UnconnectedDropdownContentWrapper,
+	'DropdownContentWrapper'
+);
+
+export default DropdownContentWrapper;

package/src/dropdown/index.js

@@ -40,6 +40,7 @@ export default function Dropdown( props ) {
 		popoverProps,
 		onClose,
 		onToggle,
+		style,
 	} = props;
 	const containerRef = useRef();
 	const [ isOpen, setIsOpen ] = useObservableState( false, onToggle );
@@ -95,6 +96,7 @@ export default function Dropdown( props ) {
 			// clicked. Making this div focusable ensures such UAs will focus
 			// it and `closeIfFocusOutside` can tell if the toggle was clicked.
 			tabIndex="-1"
+			style={ style }
 		>
 			{ renderToggle( args ) }
 			{ isOpen && (
@@ -108,11 +110,7 @@ export default function Dropdown( props ) {
 					// This value is used to ensure that the dropdowns
 					// align with the editor header by default.
 					offset={ 13 }
-					anchorRef={
-						! hasAnchorRef
-							? containerRef?.current?.firstChild // Anchor to the rendered toggle.
-							: undefined
-					}
+					anchorRef={ ! hasAnchorRef ? containerRef : undefined }
 					{ ...popoverProps }
 					className={ classnames(
 						'components-dropdown__content',

package/src/dropdown/stories/index.js

@@ -1,81 +1,72 @@
-/**
- * WordPress dependencies
- */
-import {
-	more,
-	arrowLeft,
-	arrowRight,
-	arrowUp,
-	arrowDown,
-} from '@wordpress/icons';
-
 /**
  * Internal dependencies
  */
 import Dropdown from '../';
 import Button from '../../button';
-import MenuGroup from '../../menu-group';
-import MenuItem from '../../menu-item';
-import DropdownMenu from '../../dropdown-menu';
+import { DropdownContentWrapper } from '../dropdown-content-wrapper';
 
-export default { title: 'Components/Dropdown', component: Dropdown };
+export default {
+	title: 'Components/Dropdown',
+	component: Dropdown,
+	subcomponents: { DropdownContentWrapper },
+	argTypes: {
+		expandOnMobile: { control: { type: 'boolean' } },
+		focusOnMount: {
+			control: {
+				type: 'radio',
+				options: [ 'firstElement', 'container', false ],
+			},
+		},
+		headerTitle: { control: { type: 'text' } },
+		renderContent: { control: { type: null } },
+		renderToggle: { control: { type: null } },
+	},
+};
 
-const DropdownAndDropdownMenuExample = () => {
+const Template = ( args ) => {
 	return (
-		<>
-			<div>
-				<p>This is a DropdownMenu component:</p>
-				<DropdownMenu
-					icon={ more }
-					label="Select a direction"
-					controls={ [
-						{
-							title: 'Up',
-							icon: arrowUp,
-						},
-						{
-							title: 'Right',
-							icon: arrowRight,
-						},
-						{
-							title: 'Down',
-							icon: arrowDown,
-						},
-						{
-							title: 'Left',
-							icon: arrowLeft,
-						},
-					] }
-				/>
-			</div>
-			<div>
-				<p>This is an assembled Dropdown component:</p>
-				<Dropdown
-					className="my-container-class-name"
-					contentClassName="my-popover-content-classname"
-					position="bottom right"
-					renderToggle={ ( { isOpen, onToggle } ) => (
-						<Button
-							icon={ more }
-							onClick={ onToggle }
-							aria-expanded={ isOpen }
-							label="Select a direction"
-						/>
-					) }
-					renderContent={ () => (
-						<MenuGroup>
-							<MenuItem icon={ arrowUp }>Up</MenuItem>
-							<MenuItem icon={ arrowDown }>Down</MenuItem>
-							<MenuItem icon={ arrowLeft }>Left</MenuItem>
-							<MenuItem icon={ arrowRight }>Right</MenuItem>
-						</MenuGroup>
-					) }
-				/>
-			</div>
-		</>
+		<div style={ { height: 150 } }>
+			<Dropdown { ...args } />
+		</div>
 	);
 };
 
-export const _default = () => {
-	return <DropdownAndDropdownMenuExample />;
+export const Default = Template.bind( {} );
+Default.args = {
+	position: 'bottom right',
+	renderToggle: ( { isOpen, onToggle } ) => (
+		<Button onClick={ onToggle } aria-expanded={ isOpen } isPrimary>
+			Open dropdown
+		</Button>
+	),
+	renderContent: () => <div>This is the dropdown content.</div>,
+};
+
+/**
+ * To apply more padding to the dropdown content, use the provided `<DropdownContentWrapper>`
+ * convenience wrapper. A `paddingSize` of `"medium"` is suitable for relatively larger dropdowns (default is `"small"`).
+ */
+export const WithMorePadding = Template.bind( {} );
+WithMorePadding.args = {
+	...Default.args,
+	renderContent: () => (
+		<DropdownContentWrapper paddingSize="medium">
+			Content wrapped with <code>{ `paddingSize="medium"` }</code>.
+		</DropdownContentWrapper>
+	),
+};
+
+/**
+ * The `<DropdownContentWrapper>` convenience wrapper can also be used to remove padding entirely,
+ * with a `paddingSize` of `"none"`. This can also serve as a clean foundation to add arbitrary
+ * paddings, for example when child components already have padding on their own.
+ */
+export const WithNoPadding = Template.bind( {} );
+WithNoPadding.args = {
+	...Default.args,
+	renderContent: () => (
+		<DropdownContentWrapper paddingSize="none">
+			Content wrapped with <code>{ `paddingSize="none"` }</code>.
+		</DropdownContentWrapper>
+	),
 };

package/src/dropdown/styles.ts

@@ -0,0 +1,38 @@
+/**
+ * External dependencies
+ */
+import { css } from '@emotion/react';
+import styled from '@emotion/styled';
+
+/**
+ * Internal dependencies
+ */
+import { space } from '../ui/utils/space';
+import type { DropdownContentWrapperProps } from './types';
+
+const padding = ( { paddingSize = 'small' }: DropdownContentWrapperProps ) => {
+	if ( paddingSize === 'none' ) return;
+
+	const paddingValues = {
+		small: space( 2 ),
+		medium: space( 4 ),
+	};
+
+	return css`
+		padding: ${ paddingValues[ paddingSize ] || paddingValues.small };
+	`;
+};
+
+export const DropdownContentWrapperDiv = styled.div< DropdownContentWrapperProps >`
+	// Negative margin to reset (offset) the default padding on .components-popover__content
+	margin-left: ${ space( -2 ) };
+	margin-right: ${ space( -2 ) };
+	&:first-of-type {
+		margin-top: ${ space( -2 ) };
+	}
+	&:last-of-type {
+		margin-bottom: ${ space( -2 ) };
+	}
+
+	${ padding };
+`;

package/src/dropdown/types.ts

@@ -0,0 +1,8 @@
+export type DropdownContentWrapperProps = {
+	/**
+	 * Amount of padding to apply on the dropdown content.
+	 *
+	 * @default 'small'
+	 */
+	paddingSize?: 'none' | 'small' | 'medium';
+};

package/src/dropdown-menu/stories/index.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { text } from '@storybook/addon-knobs';
+import { text, boolean } from '@storybook/addon-knobs';
 
 /**
  * Internal dependencies
@@ -25,6 +25,10 @@ export const _default = () => {
 	const label = text( 'Label', 'Select a direction.' );
 	const firstMenuItemLabel = text( 'First Menu Item Label', 'Up' );
 	const secondMenuItemLabel = text( 'First Menu Item Label', 'Down' );
+	const toggleButtonTootip = boolean(
+		'Show tooltip on a toggle button',
+		true
+	);
 
 	const controls = [
 		{
@@ -37,5 +41,12 @@ export const _default = () => {
 		},
 	];
 
-	return <DropdownMenu icon={ menu } label={ label } controls={ controls } />;
+	return (
+		<DropdownMenu
+			icon={ menu }
+			label={ label }
+			controls={ controls }
+			toggleProps={ { showTooltip: toggleButtonTootip } }
+		/>
+	);
 };

package/src/duotone-picker/custom-duotone-bar.js

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import CustomGradientBar from '../custom-gradient-bar';
+import CustomGradientBar from '../custom-gradient-picker/gradient-bar';
 
 import {
 	getColorStopsFromColors,