@wordpress/components 22.1.0 → 23.1.0

package/src/disabled/test/index.tsx

@@ -9,6 +9,8 @@ import { render, screen } from '@testing-library/react';
 import Disabled from '../';
 import userEvent from '@testing-library/user-event';
 
+jest.useFakeTimers();
+
 describe( 'Disabled', () => {
 	const Form = () => (
 		<form title="form">
@@ -18,48 +20,58 @@ describe( 'Disabled', () => {
 	);
 
 	it( 'will disable all fields', () => {
-		const { container } = render(
-			<Disabled>
+		render(
+			<Disabled data-testid="disabled-wrapper">
 				<Form />
 			</Disabled>
 		);
 
-		expect( container.firstChild ).toHaveAttribute( 'inert' );
+		expect( screen.getByTestId( 'disabled-wrapper' ) ).toHaveAttribute(
+			'inert'
+		);
 	} );
 
 	it( 'should cleanly un-disable via reconciliation', () => {
 		const MaybeDisable = ( { isDisabled = true } ) =>
 			isDisabled ? (
-				<Disabled>
+				<Disabled data-testid="disabled-wrapper">
 					<Form />
 				</Disabled>
 			) : (
 				<Form />
 			);
 
-		const { container, rerender } = render( <MaybeDisable /> );
+		const { rerender } = render( <MaybeDisable /> );
 
-		expect( container.firstChild ).toHaveAttribute( 'inert' );
+		expect( screen.getByTestId( 'disabled-wrapper' ) ).toHaveAttribute(
+			'inert'
+		);
 
 		rerender( <MaybeDisable isDisabled={ false } /> );
 
-		expect( container.firstChild ).not.toHaveAttribute( 'inert' );
+		expect(
+			screen.queryByTestId( 'disabled-wrapper' )
+		).not.toBeInTheDocument();
 	} );
 
 	it( 'will disable or enable descendant fields based on the isDisabled prop value', () => {
 		const MaybeDisable = ( { isDisabled = true } ) => (
-			<Disabled isDisabled={ isDisabled }>
+			<Disabled isDisabled={ isDisabled } data-testid="disabled-wrapper">
 				<Form />
 			</Disabled>
 		);
 
-		const { rerender, container } = render( <MaybeDisable /> );
+		const { rerender } = render( <MaybeDisable /> );
 
-		expect( container.firstChild ).toHaveAttribute( 'inert' );
+		expect( screen.getByTestId( 'disabled-wrapper' ) ).toHaveAttribute(
+			'inert'
+		);
 
 		rerender( <MaybeDisable isDisabled={ false } /> );
 
-		expect( container.firstChild ).not.toHaveAttribute( 'inert' );
+		expect( screen.getByTestId( 'disabled-wrapper' ) ).not.toHaveAttribute(
+			'inert'
+		);
 	} );
 
 	it( 'should preserve input values when toggling the isDisabled prop', async () => {

package/src/dropdown/README.md

@@ -32,96 +32,91 @@ const MyDropdown = () => (
 
 The component accepts the following props. Props not included in this set will be applied to the element wrapping Popover content.
 
-### className
+### `className`: `string`
 
 className of the global container
 
--   Type: `String`
 -   Required: No
 
-### contentClassName
+### `contentClassName`: `string`
 
 If you want to target the dropdown menu for styling purposes, you need to provide a contentClassName because it's not being rendered as a child of the container node.
 
--   Type: `String`
 -   Required: No
 
-### position
+### `expandOnMobile`: `boolean`
 
-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.
+Opt-in prop to show popovers fullscreen on mobile.
 
--   Type: `String`
 -   Required: No
--   Default: `"top center"`
-
-### renderToggle
-
-A callback invoked to render the Dropdown Toggle Button.
-
--   Type: `Function`
--   Required: Yes
+-   Default: `false`
 
-The first argument of the callback is an object containing the following properties:
+### `focusOnMount`: `'firstElement' | boolean`
 
--   `isOpen`: whether the dropdown menu is opened or not
--   `onToggle`: A function switching the dropdown menu's state from open to closed and vice versa
--   `onClose`: A function that closes the menu if invoked
+By default, the _first tabbable element_ in the popover will receive focus when it mounts. This is the same as setting this prop to `"firstElement"`.
 
-### renderContent
+Specifying a `true` value will focus the container instead.
 
-A callback invoked to render the content of the dropdown menu. Its first argument is the same as the `renderToggle` prop.
+Specifying a `false` value disables the focus handling entirely (this should only be done when an appropriately accessible substitute behavior exists).
 
--   Type: `Function`
--   Required: Yes
+-   Required: No
+-   Default: `"firstElement"`
 
-### expandOnMobile
+### `headerTitle`: `string`
 
-Opt-in prop to show popovers fullscreen on mobile.
+Set this to customize the text that is shown in the dropdown's header when it is fullscreen on mobile.
 
--   Type: `Boolean`
 -   Required: No
--   Default: `false`
 
-### headerTitle
+### `onClose`: `() => void`
 
-Set this to customize the text that is shown in the dropdown's header when it is fullscreen on mobile.
+A callback invoked when the popover should be closed.
 
--   Type: `String`
 -   Required: No
 
-### focusOnMount
-
-By default, the _first tabbable element_ in the popover will receive focus when it mounts. This is the same as setting this prop to `"firstElement"`.
+### `onToggle`: `( willOpen: boolean ) => void`
 
-Specifying a `true` value will focus the container instead.
+A callback invoked when the state of the popover changes from open to closed and vice versa.
 
-Specifying a `false` value disables the focus handling entirely (this should only be done when an appropriately accessible substitute behavior exists).
+The callback receives a boolean as a parameter. If `true`, the popover will open. If `false`, the popover will close.
 
--   Type: `'firstElement' | boolean`
 -   Required: No
--   Default: `"firstElement"`
 
-### popoverProps
+### `popoverProps`: `WordPressComponentProps< Omit< PopoverProps, 'children' > 'div', false	>`
 
 Properties of popoverProps object will be passed as props to the `Popover` component.
 
 Use this object to access properties/features of the `Popover` component that are not already exposed in the `Dropdown` component, e.g.: the ability to have the popover without an arrow.
 
--   Type: `Object`
 -   Required: No
 
-### onClose
+### `position`: `PopoverProps[ 'position' ]`
 
-A callback invoked when the popover should be closed.
+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.
 
--   Type: `Function`
 -   Required: No
+-   Default: `"top center"`
 
-### onToggle
+### `renderContent`: `( props: CallbackProps ) => ReactNode`
 
-A callback invoked when the state of the popover changes from open to closed and vice versa.
+A callback invoked to render the content of the dropdown menu.
 
-The callback receives a boolean as a parameter. If `true`, the popover will open. If `false`, the popover will close.
+- `isOpen`: whether the dropdown menu is opened or not
+- `onToggle`: A function switching the dropdown menu's state from open to closed and vice versa
+- `onClose`: A function that closes the menu if invoked
+
+-   Required: Yes
+
+### `renderToggle`: `( props: CallbackProps ) => ReactNode`
+
+A callback invoked to render the Dropdown Toggle Button.
+
+Its props are the same as the `renderContent` props.
+
+-   Required: Yes
+
+### `style`: `React.CSSProperties`
+
+The style of the global container
 
--   Type: `Function`
 -   Required: No

package/src/dropdown/{index.js → index.tsx}

@@ -1,35 +1,39 @@
-// @ts-nocheck
 /**
  * External dependencies
  */
 import classnames from 'classnames';
+import type { ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
  */
-import { useRef, useEffect, useState } from '@wordpress/element';
+import { forwardRef, useEffect, useRef, useState } from '@wordpress/element';
 import { useMergeRefs } from '@wordpress/compose';
 
 /**
  * Internal dependencies
  */
 import Popover from '../popover';
+import type { DropdownProps } from './types';
 
-function useObservableState( initialState, onStateChange ) {
+function useObservableState(
+	initialState: boolean,
+	onStateChange?: ( newState: boolean ) => void
+) {
 	const [ state, setState ] = useState( initialState );
 	return [
 		state,
-		( value ) => {
+		( value: boolean ) => {
 			setState( value );
 			if ( onStateChange ) {
 				onStateChange( value );
 			}
 		},
-	];
+	] as const;
 }
 
-export default function Dropdown( props ) {
-	const {
+function UnforwardedDropdown(
+	{
 		renderContent,
 		renderToggle,
 		className,
@@ -42,12 +46,14 @@ export default function Dropdown( props ) {
 		onClose,
 		onToggle,
 		style,
-	} = props;
+	}: DropdownProps,
+	forwardedRef: ForwardedRef< any >
+) {
 	// Use internal state instead of a ref to make sure that the component
 	// re-renders when the popover's anchor updates.
 	const [ fallbackPopoverAnchor, setFallbackPopoverAnchor ] =
-		useState( null );
-	const containerRef = useRef();
+		useState< HTMLDivElement | null >( null );
+	const containerRef = useRef< HTMLDivElement >();
 	const [ isOpen, setIsOpen ] = useObservableState( false, onToggle );
 
 	useEffect(
@@ -70,8 +76,13 @@ export default function Dropdown( props ) {
 	 * case a dialog has opened, allowing focus to return when it's dismissed.
 	 */
 	function closeIfFocusOutside() {
+		if ( ! containerRef.current ) {
+			return;
+		}
+
 		const { ownerDocument } = containerRef.current;
-		const dialog = ownerDocument.activeElement.closest( '[role="dialog"]' );
+		const dialog =
+			ownerDocument?.activeElement?.closest( '[role="dialog"]' );
 		if (
 			! containerRef.current.contains( ownerDocument.activeElement ) &&
 			( ! dialog || dialog.contains( containerRef.current ) )
@@ -99,11 +110,15 @@ export default function Dropdown( props ) {
 	return (
 		<div
 			className={ classnames( 'components-dropdown', className ) }
-			ref={ useMergeRefs( [ setFallbackPopoverAnchor, containerRef ] ) }
+			ref={ useMergeRefs( [
+				containerRef,
+				forwardedRef,
+				setFallbackPopoverAnchor,
+			] ) }
 			// Some UAs focus the closest focusable parent when the toggle is
 			// clicked. Making this div focusable ensures such UAs will focus
 			// it and `closeIfFocusOutside` can tell if the toggle was clicked.
-			tabIndex="-1"
+			tabIndex={ -1 }
 			style={ style }
 		>
 			{ renderToggle( args ) }
@@ -136,3 +151,32 @@ export default function Dropdown( props ) {
 		</div>
 	);
 }
+
+/**
+ * Renders a button that opens a floating content modal when clicked.
+ *
+ * ```jsx
+ * import { Button, Dropdown } from '@wordpress/components';
+ *
+ * const MyDropdown = () => (
+ *   <Dropdown
+ *     className="my-container-class-name"
+ *     contentClassName="my-popover-content-classname"
+ *     position="bottom right"
+ *     renderToggle={ ( { isOpen, onToggle } ) => (
+ *       <Button
+ *         variant="primary"
+ *         onClick={ onToggle }
+ *         aria-expanded={ isOpen }
+ *       >
+ *         Toggle Popover!
+ *       </Button>
+ *     ) }
+ *     renderContent={ () => <div>This is the content of the popover.</div> }
+ *   />
+ * );
+ * ```
+ */
+export const Dropdown = forwardRef( UnforwardedDropdown );
+
+export default Dropdown;

package/src/dropdown/stories/{index.js → index.tsx}

@@ -1,29 +1,38 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
 /**
  * Internal dependencies
  */
-import Dropdown from '../';
+import Dropdown from '..';
 import Button from '../../button';
 import { DropdownContentWrapper } from '../dropdown-content-wrapper';
 
-export default {
+const meta: ComponentMeta< typeof Dropdown > = {
 	title: 'Components/Dropdown',
 	component: Dropdown,
 	subcomponents: { DropdownContentWrapper },
 	argTypes: {
-		expandOnMobile: { control: { type: 'boolean' } },
 		focusOnMount: {
 			control: {
 				type: 'radio',
 				options: [ 'firstElement', true, false ],
 			},
 		},
-		headerTitle: { control: { type: 'text' } },
 		renderContent: { control: { type: null } },
 		renderToggle: { control: { type: null } },
 	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+	},
 };
+export default meta;
 
-const Template = ( args ) => {
+const Template: ComponentStory< typeof Dropdown > = ( args ) => {
 	return (
 		<div style={ { height: 150 } }>
 			<Dropdown { ...args } />
@@ -31,7 +40,7 @@ const Template = ( args ) => {
 	);
 };
 
-export const Default = Template.bind( {} );
+export const Default: ComponentStory< typeof Dropdown > = Template.bind( {} );
 Default.args = {
 	position: 'bottom right',
 	renderToggle: ( { isOpen, onToggle } ) => (
@@ -46,7 +55,9 @@ Default.args = {
  * 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( {} );
+export const WithMorePadding: ComponentStory< typeof Dropdown > = Template.bind(
+	{}
+);
 WithMorePadding.args = {
 	...Default.args,
 	renderContent: () => (
@@ -61,7 +72,9 @@ WithMorePadding.args = {
  * 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( {} );
+export const WithNoPadding: ComponentStory< typeof Dropdown > = Template.bind(
+	{}
+);
 WithNoPadding.args = {
 	...Default.args,
 	renderContent: () => (

package/src/dropdown/test/index.tsx

@@ -0,0 +1,88 @@
+/**
+ * External dependencies
+ */
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+/**
+ * Internal dependencies
+ */
+import Dropdown from '..';
+
+jest.useFakeTimers();
+
+describe( 'Dropdown', () => {
+	it( 'should toggle the dropdown properly', async () => {
+		const user = userEvent.setup( {
+			advanceTimers: jest.advanceTimersByTime,
+		} );
+		const { unmount } = render(
+			<Dropdown
+				className="container"
+				contentClassName="content"
+				renderToggle={ ( { isOpen, onToggle } ) => (
+					<button aria-expanded={ isOpen } onClick={ onToggle }>
+						Toggle
+					</button>
+				) }
+				renderContent={ () => <span>test</span> }
+			/>
+		);
+
+		const button = screen.getByRole( 'button', { expanded: false } );
+
+		expect( button ).toBeVisible();
+		expect( screen.queryByText( 'test' ) ).not.toBeInTheDocument();
+
+		await user.click( button );
+
+		expect(
+			screen.getByRole( 'button', { expanded: true } )
+		).toBeVisible();
+
+		await waitFor( () =>
+			expect( screen.queryByText( 'test' ) ).toBeVisible()
+		);
+
+		// Cleanup remaining effects, like the delayed popover positioning
+		unmount();
+	} );
+
+	it( 'should close the dropdown when calling onClose', async () => {
+		const user = userEvent.setup( {
+			advanceTimers: jest.advanceTimersByTime,
+		} );
+		render(
+			<Dropdown
+				className="container"
+				contentClassName="content"
+				renderToggle={ ( { isOpen, onToggle, onClose } ) => [
+					<button
+						key="open"
+						className="open"
+						aria-expanded={ isOpen }
+						onClick={ onToggle }
+					>
+						Toggle
+					</button>,
+					<button key="close" className="close" onClick={ onClose }>
+						close
+					</button>,
+				] }
+				renderContent={ () => <span>test</span> }
+			/>
+		);
+
+		expect( screen.queryByText( 'test' ) ).not.toBeInTheDocument();
+
+		await user.click( screen.getByRole( 'button', { name: 'Toggle' } ) );
+
+		await waitFor( () =>
+			expect( screen.getByText( 'test' ) ).toBeVisible()
+		);
+
+		await user.click( screen.getByRole( 'button', { name: 'close' } ) );
+
+		expect( screen.queryByText( 'test' ) ).not.toBeInTheDocument();
+	} );
+} );

package/src/dropdown/types.ts

@@ -1,3 +1,20 @@
+/**
+ * External dependencies
+ */
+import type { ComponentPropsWithoutRef, CSSProperties, ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type Popover from '../popover';
+import type { PopoverProps } from '../popover/types';
+
+type CallbackProps = {
+	isOpen: boolean;
+	onToggle: () => void;
+	onClose: () => void;
+};
+
 export type DropdownContentWrapperProps = {
 	/**
 	 * Amount of padding to apply on the dropdown content.
@@ -6,3 +23,93 @@ export type DropdownContentWrapperProps = {
 	 */
 	paddingSize?: 'none' | 'small' | 'medium';
 };
+
+export type DropdownProps = {
+	/**
+	 * The className of the global container.
+	 */
+	className?: string;
+	/**
+	 * If you want to target the dropdown menu for styling purposes,
+	 * you need to provide a contentClassName because it's not being rendered
+	 * as a child of the container node.
+	 */
+	contentClassName?: string;
+	/**
+	 * Opt-in prop to show popovers fullscreen on mobile.
+	 *
+	 * @default false
+	 */
+	expandOnMobile?: boolean;
+	/**
+	 * By default, the first tabbable element in the popover will receive focus
+	 * when it mounts. This is the same as setting this prop to "firstElement".
+	 * Specifying a true value will focus the container instead.
+	 * Specifying a false value disables the focus handling entirely
+	 * (this should only be done when an appropriately accessible
+	 * substitute behavior exists).
+	 *
+	 * @default 'firstElement'
+	 */
+	focusOnMount?: 'firstElement' | boolean;
+	/**
+	 * Set this to customize the text that is shown in the dropdown's header
+	 * when it is fullscreen on mobile.
+	 */
+	headerTitle?: string;
+	/**
+	 * A callback invoked when the popover should be closed.
+	 */
+	onClose?: () => void;
+	/**
+	 * A callback invoked when the state of the popover changes
+	 * from open to closed and vice versa.
+	 * The callback receives a boolean as a parameter.
+	 * If true, the popover will open.
+	 * If false, the popover will close.
+	 */
+	onToggle?: ( willOpen: boolean ) => void;
+	/**
+	 * Properties of popoverProps object will be passed as props
+	 * to the Popover component.
+	 * Use this object to access properties/features
+	 * of the Popover component that are not already exposed
+	 * in the Dropdown component,
+	 * e.g.: the ability to have the popover without an arrow.
+	 */
+	popoverProps?: Omit<
+		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.
+	 */
+	renderContent: ( props: CallbackProps ) => ReactNode;
+	/**
+	 * A callback invoked to render the Dropdown Toggle Button.
+	 *
+	 * The first argument of the callback is an object
+	 * containing the following properties:
+	 *
+	 * - isOpen: whether the dropdown menu is opened or not
+	 * - onToggle: A function switching the dropdown menu's state
+	 * from open to closed and vice versa
+	 * - onClose: A function that closes the menu if invoked
+	 */
+	renderToggle: ( props: CallbackProps ) => ReactNode;
+	/**
+	 * The style of the global container.
+	 */
+	style?: CSSProperties;
+};

package/src/dropdown-menu/README.md

@@ -101,14 +101,13 @@ const MyDropdownMenu = () => (
 Alternatively, specify a `children` function which returns elements valid for use in a DropdownMenu: `MenuItem`, `MenuItemsChoice`, or `MenuGroup`.
 
 ```jsx
-import { Fragment } from '@wordpress/element';
 import { DropdownMenu, MenuGroup, MenuItem } from '@wordpress/components';
 import { more, arrowUp, arrowDown, trash } from '@wordpress/icons';
 
 const MyDropdownMenu = () => (
 	<DropdownMenu icon={ more } label="Select a direction">
 		{ ( { onClose } ) => (
-			<Fragment>
+			<>
 				<MenuGroup>
 					<MenuItem icon={ arrowUp } onClick={ onClose }>
 						Move Up
@@ -122,7 +121,7 @@ const MyDropdownMenu = () => (
 						Remove
 					</MenuItem>
 				</MenuGroup>
-			</Fragment>
+			</>
 		) }
 	</DropdownMenu>
 );