@wordpress/components 19.14.0 → 19.17.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/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/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/index.js

@@ -3,7 +3,6 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { flatMap, isEmpty } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -59,13 +58,13 @@ function DropdownMenu( dropdownMenuProps ) {
 		noIcons,
 	} = dropdownMenuProps;
 
-	if ( isEmpty( controls ) && ! isFunction( children ) ) {
+	if ( ! controls?.length && ! isFunction( children ) ) {
 		return null;
 	}
 
 	// Normalize controls to nested array of objects (sets of controls)
 	let controlSets;
-	if ( ! isEmpty( controls ) ) {
+	if ( controls?.length ) {
 		controlSets = controls;
 		if ( ! Array.isArray( controlSets[ 0 ] ) ) {
 			controlSets = [ controlSets ];
@@ -146,7 +145,7 @@ function DropdownMenu( dropdownMenuProps ) {
 				return (
 					<NavigableMenu { ...mergedMenuProps } role="menu">
 						{ isFunction( children ) ? children( props ) : null }
-						{ flatMap( controlSets, ( controlSet, indexOfSet ) =>
+						{ controlSets?.flatMap( ( controlSet, indexOfSet ) =>
 							controlSet.map( ( control, indexOfControl ) => (
 								<Button
 									key={ [

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

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { flatMap, isEmpty } from 'lodash';
 import { Platform } from 'react-native';
 /**
  * WordPress dependencies
@@ -53,13 +52,13 @@ function DropdownMenu( {
 	popoverProps,
 	toggleProps,
 } ) {
-	if ( isEmpty( controls ) && ! isFunction( children ) ) {
+	if ( ! controls?.length && ! isFunction( children ) ) {
 		return null;
 	}
 
 	// Normalize controls to nested array of objects (sets of controls)
 	let controlSets;
-	if ( ! isEmpty( controls ) ) {
+	if ( controls?.length ) {
 		controlSets = controls;
 		if ( ! Array.isArray( controlSets[ 0 ] ) ) {
 			controlSets = [ controlSets ];
@@ -131,8 +130,7 @@ function DropdownMenu( {
 							title={ label }
 							style={ { paddingLeft: 0, paddingRight: 0 } }
 						>
-							{ flatMap(
-								controlSets,
+							{ controlSets?.flatMap(
 								( controlSet, indexOfSet ) =>
 									controlSet.map(
 										( control, indexOfControl ) => (

package/src/elevation/README.md

@@ -33,46 +33,45 @@ function Example() {
 
 Size of the shadow value when active (see the `value` and `isInteractive` props).
 
-- Required: No
+-   Required: No
 
 ### `borderRadius`: `CSSProperties[ 'borderRadius' ]`
 
 Renders the border-radius of the shadow.
 
-- Required: No
-- Default: `inherit`
+-   Required: No
+-   Default: `inherit`
 
 ### `focus`: `number`
 
-Size of the shadow value when focused (see the `value` and `isInteractive` props).
+Size of the shadow value when focused (see the `value` and `isInteractive`props).
 
-- Required: No
+-   Required: No
 
 ### `hover`: `number`
 
-Size of the shadow value when hovered  (see the `value` and `isInteractive` props).
+Size of the shadow value when hovered (see the `value` and `isInteractive` props).
 
-- Required: No
+-   Required: No
 
 ### `isInteractive`: `boolean`
 
 Determines if `hover`, `active`, and `focus` shadow values should be automatically calculated and rendered.
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`
 
 ### `offset`: `number`
 
 Dimensional offsets (margin) for the shadow.
 
-- Required: No
-- Default: `0`
+-   Required: No
+-   Default: `0`
 
-### `value`
-
-**Type**: `number`
+### `value`: `number`
 
 Size of the shadow, based on the Style system's elevation system. The `value` determines the strength of the shadow, which sense of depth.
+
 In the example below, `isInteractive` is activated to give a better sense of depth.
 
 ```jsx
@@ -86,3 +85,6 @@ function Example() {
 	);
 }
 ```
+
+-   Required: No
+-   Default: `0`