@wordpress/components 24.0.0 → 25.1.0

package/src/date-time/README.md

@@ -26,8 +26,6 @@ const MyDateTimePicker = () => {
 			currentDate={ date }
 			onChange={ ( newDate ) => setDate( newDate ) }
 			is12Hour={ true }
-			__nextRemoveHelpButton
-			__nextRemoveResetButton
 		/>
 	);
 };
@@ -83,17 +81,3 @@ The day that the week should start on. 0 for Sunday, 1 for Monday, etc.
 
 - Required: No
 - Default: 0
-
-### `__nextRemoveHelpButton`: `boolean`
-
-Start opting in to not displaying a Help button which will become the default in a future version.
-
-- Required: No
-- Default: `false`
-
-### `__nextRemoveResetButton`: `boolean`
-
-Start opting in to not displaying a Reset button which will become the default in a future version.
-
-- Required: No
-- Default: `false`

package/src/date-time/date-time/index.tsx

@@ -6,21 +6,16 @@ import type { ForwardedRef } from 'react';
 /**
  * WordPress dependencies
  */
-import { useState, forwardRef } from '@wordpress/element';
+import { forwardRef } from '@wordpress/element';
 import { __, _x } from '@wordpress/i18n';
-import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
  */
-import Button from '../../button';
 import { default as DatePicker } from '../date';
 import { default as TimePicker } from '../time';
 import type { DateTimePickerProps } from '../types';
-import { Wrapper, CalendarHelp } from './styles';
-import { HStack } from '../../h-stack';
-import { Heading } from '../../heading';
-import { Spacer } from '../../spacer';
+import { Wrapper } from './styles';
 
 export { DatePicker, TimePicker };
 
@@ -35,157 +30,26 @@ function UnforwardedDateTimePicker(
 		onChange,
 		events,
 		startOfWeek,
-		__nextRemoveHelpButton = false,
-		__nextRemoveResetButton = false,
 	}: DateTimePickerProps,
 	ref: ForwardedRef< any >
 ) {
-	if ( ! __nextRemoveHelpButton ) {
-		deprecated( 'Help button in wp.components.DateTimePicker', {
-			since: '13.4',
-			version: '15.8', // One year of plugin releases.
-			hint: 'Set the `__nextRemoveHelpButton` prop to `true` to remove this warning and opt in to the new behaviour, which will become the default in a future version.',
-		} );
-	}
-	if ( ! __nextRemoveResetButton ) {
-		deprecated( 'Reset button in wp.components.DateTimePicker', {
-			since: '13.4',
-			version: '15.8', // One year of plugin releases.
-			hint: 'Set the `__nextRemoveResetButton` prop to `true` to remove this warning and opt in to the new behaviour, which will become the default in a future version.',
-		} );
-	}
-
-	const [ calendarHelpIsVisible, setCalendarHelpIsVisible ] =
-		useState( false );
-
-	function onClickDescriptionToggle() {
-		setCalendarHelpIsVisible( ! calendarHelpIsVisible );
-	}
-
 	return (
 		<Wrapper ref={ ref } className="components-datetime" spacing={ 4 }>
-			{ ! calendarHelpIsVisible && (
-				<>
-					<TimePicker
-						currentTime={ currentDate }
-						onChange={ onChange }
-						is12Hour={ is12Hour }
-					/>
-					<DatePicker
-						currentDate={ currentDate }
-						onChange={ onChange }
-						isInvalidDate={ isInvalidDate }
-						events={ events }
-						onMonthPreviewed={ onMonthPreviewed }
-						startOfWeek={ startOfWeek }
-					/>
-				</>
-			) }
-			{ calendarHelpIsVisible && (
-				<CalendarHelp
-					className="components-datetime__calendar-help" // Unused, for backwards compatibility.
-				>
-					<Heading level={ 4 }>{ __( 'Click to Select' ) }</Heading>
-					<ul>
-						<li>
-							{ __(
-								'Click the right or left arrows to select other months in the past or the future.'
-							) }
-						</li>
-						<li>{ __( 'Click the desired day to select it.' ) }</li>
-					</ul>
-					<Heading level={ 4 }>
-						{ __( 'Navigating with a keyboard' ) }
-					</Heading>
-					<ul>
-						<li>
-							<abbr
-								aria-label={ _x( 'Enter', 'keyboard button' ) }
-							>
-								↵
-							</abbr>
-							{
-								' ' /* JSX removes whitespace, but a space is required for screen readers. */
-							}
-							<span>{ __( 'Select the date in focus.' ) }</span>
-						</li>
-						<li>
-							<abbr aria-label={ __( 'Left and Right Arrows' ) }>
-								←/→
-							</abbr>
-							{
-								' ' /* JSX removes whitespace, but a space is required for screen readers. */
-							}
-							{ __(
-								'Move backward (left) or forward (right) by one day.'
-							) }
-						</li>
-						<li>
-							<abbr aria-label={ __( 'Up and Down Arrows' ) }>
-								↑/↓
-							</abbr>
-							{
-								' ' /* JSX removes whitespace, but a space is required for screen readers. */
-							}
-							{ __(
-								'Move backward (up) or forward (down) by one week.'
-							) }
-						</li>
-						<li>
-							<abbr aria-label={ __( 'Page Up and Page Down' ) }>
-								{ __( 'PgUp/PgDn' ) }
-							</abbr>
-							{
-								' ' /* JSX removes whitespace, but a space is required for screen readers. */
-							}
-							{ __(
-								'Move backward (PgUp) or forward (PgDn) by one month.'
-							) }
-						</li>
-						<li>
-							<abbr aria-label={ __( 'Home and End' ) }>
-								{ /* Translators: Home/End reffer to the 'Home' and 'End' buttons on the keyboard.*/ }
-								{ __( 'Home/End' ) }
-							</abbr>
-							{
-								' ' /* JSX removes whitespace, but a space is required for screen readers. */
-							}
-							{ __(
-								'Go to the first (Home) or last (End) day of a week.'
-							) }
-						</li>
-					</ul>
-				</CalendarHelp>
-			) }
-			{ ( ! __nextRemoveResetButton || ! __nextRemoveHelpButton ) && (
-				<HStack
-					className="components-datetime__buttons" // Unused, for backwards compatibility.
-				>
-					{ ! __nextRemoveResetButton &&
-						! calendarHelpIsVisible &&
-						currentDate && (
-							<Button
-								className="components-datetime__date-reset-button" // Unused, for backwards compatibility.
-								variant="link"
-								onClick={ () => onChange?.( null ) }
-							>
-								{ __( 'Reset' ) }
-							</Button>
-						) }
-					<Spacer />
-					{ ! __nextRemoveHelpButton && (
-						<Button
-							className="components-datetime__date-help-toggle" // Unused, for backwards compatibility.
-							variant="link"
-							onClick={ onClickDescriptionToggle }
-						>
-							{ calendarHelpIsVisible
-								? __( 'Close' )
-								: __( 'Calendar Help' ) }
-						</Button>
-					) }
-				</HStack>
-			) }
+			<>
+				<TimePicker
+					currentTime={ currentDate }
+					onChange={ onChange }
+					is12Hour={ is12Hour }
+				/>
+				<DatePicker
+					currentDate={ currentDate }
+					onChange={ onChange }
+					isInvalidDate={ isInvalidDate }
+					events={ events }
+					onMonthPreviewed={ onMonthPreviewed }
+					startOfWeek={ startOfWeek }
+				/>
+			</>
 		</Wrapper>
 	);
 }
@@ -207,8 +71,6 @@ function UnforwardedDateTimePicker(
  *       currentDate={ date }
  *       onChange={ ( newDate ) => setDate( newDate ) }
  *       is12Hour
- *       __nextRemoveHelpButton
- *       __nextRemoveResetButton
  *     />
  *   );
  * };

package/src/date-time/date-time/styles.ts

@@ -11,7 +11,3 @@ import { VStack } from '../../v-stack';
 export const Wrapper = styled( VStack )`
 	box-sizing: border-box;
 `;
-
-export const CalendarHelp = styled.div`
-	min-width: 260px;
-`;

package/src/date-time/stories/date-time.tsx

@@ -52,10 +52,6 @@ const Template: ComponentStory< typeof DateTimePicker > = ( {
 export const Default: ComponentStory< typeof DateTimePicker > = Template.bind(
 	{}
 );
-Default.args = {
-	__nextRemoveHelpButton: true,
-	__nextRemoveResetButton: true,
-};
 
 export const WithEvents: ComponentStory< typeof DateTimePicker > =
 	Template.bind( {} );

package/src/date-time/types.ts

@@ -73,20 +73,4 @@ export type DateTimePickerProps = Omit< DatePickerProps, 'onChange' > &
 		 * passed the date and time as an argument.
 		 */
 		onChange?: ( date: string | null ) => void;
-
-		/**
-		 * Start opting in to not displaying a Help button which will become the
-		 * default in a future version.
-		 *
-		 * @default false
-		 */
-		__nextRemoveHelpButton?: boolean;
-
-		/**
-		 * Start opting in to not displaying a Reset button which will become
-		 * the default in a future version.
-		 *
-		 * @default false
-		 */
-		__nextRemoveResetButton?: boolean;
 	};

package/src/dropdown-menu/README.md

@@ -131,80 +131,70 @@ const MyDropdownMenu = () => (
 
 The component accepts the following props:
 
-#### icon
+#### `icon`: `string | null`
 
 The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug to be shown in the collapsed menu button.
 
--   Type: `String|null`
 -   Required: No
 -   Default: `"menu"`
 
 See also: [https://developer.wordpress.org/resource/dashicons/](https://developer.wordpress.org/resource/dashicons/)
 
-#### label
+#### `label`: `string`
 
 A human-readable label to present as accessibility text on the focused collapsed menu button.
 
--   Type: `String`
 -   Required: Yes
 
-#### controls
+#### `controls:` `DropdownOption[] | DropdownOption[][]`
 
-An array of objects describing the options to be shown in the expanded menu.
+An array or nested array of objects describing the options to be shown in the expanded menu.
 
 Each object should include an `icon` [Dashicon](https://developer.wordpress.org/resource/dashicons/) slug string, a human-readable `title` string, `isDisabled` boolean flag and an `onClick` function callback to invoke when the option is selected.
 
-A valid DropdownMenu must specify one or the other of a `controls` or `children` prop.
-
--   Type: `Array`
+A valid DropdownMenu must specify a `controls` or `children` prop, or both.
 -   Required: No
 
-#### children
+#### `children`: `( callbackProps: DropdownCallbackProps ) => ReactNode`
 
 A [function render prop](https://reactjs.org/docs/render-props.html#using-props-other-than-render) which should return an element or elements valid for use in a DropdownMenu: `MenuItem`, `MenuItemsChoice`, or `MenuGroup`. Its first argument is a props object including the same values as given to a [`Dropdown`'s `renderContent`](/packages/components/src/dropdown#rendercontent) (`isOpen`, `onToggle`, `onClose`).
 
-A valid DropdownMenu must specify one or the other of a `controls` or `children` prop.
+A valid DropdownMenu must specify a `controls` or `children` prop, or both.
 
--   Type: `Function`
 -   Required: No
 
 See also: [https://developer.wordpress.org/resource/dashicons/](https://developer.wordpress.org/resource/dashicons/)
 
-#### className
+#### `className`: `string`
 
 A class name to apply to the dropdown menu's toggle element wrapper.
 
--   Type: `String`
 -   Required: No
 
-#### popoverProps
+#### `popoverProps`: `DropdownProps[ 'popoverProps' ]`
 
 Properties of `popoverProps` object will be passed as props to the nested `Popover` component.
 Use this object to modify props available for the `Popover` component that are not already exposed in the `DropdownMenu` component, e.g.: the direction in which the popover should open relative to its parent node set with `position` prop.
 
--   Type: `Object`
 -   Required: No
 
-#### toggleProps
+#### `toggleProps`: `ToggleProps`
 
 Properties of `toggleProps` object will be passed as props to the nested `Button` component in the `renderToggle` implementation of the `Dropdown` component used internally.
 Use this object to modify props available for the `Button` component that are not already exposed in the `DropdownMenu` component, e.g.: the tooltip text displayed on hover set with `tooltip` prop.
 
--   Type: `Object`
 -   Required: No
 
-#### menuProps
+#### `menuProps`: `NavigableContainerProps`
 
 Properties of `menuProps` object will be passed as props to the nested `NavigableMenu` component in the `renderContent` implementation of the `Dropdown` component used internally.
 Use this object to modify props available for the `NavigableMenu` component that are not already exposed in the `DropdownMenu` component, e.g.: the orientation of the menu set with `orientation` prop.
 
--   Type: `Object`
 -   Required: No
 
-#### disableOpenOnArrowDown
+#### `disableOpenOnArrowDown`: `boolean`
 
 In some contexts, the arrow down key used to open the dropdown menu might need to be disabled—for example when that key is used to perform another action.
 
--   Type: `boolean`
 -   Required: No
 -   Default: `false`

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

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * External dependencies
  */
@@ -15,9 +14,12 @@ import { menu } from '@wordpress/icons';
 import Button from '../button';
 import Dropdown from '../dropdown';
 import { NavigableMenu } from '../navigable-container';
+import type { DropdownMenuProps, DropdownOption } from './types';
 
-function mergeProps( defaultProps = {}, props = {} ) {
-	const mergedProps = {
+function mergeProps<
+	T extends { className?: string; [ key: string ]: unknown }
+>( defaultProps: Partial< T > = {}, props: T = {} as T ) {
+	const mergedProps: T = {
 		...defaultProps,
 		...props,
 	};
@@ -32,17 +34,92 @@ function mergeProps( defaultProps = {}, props = {} ) {
 	return mergedProps;
 }
 
+function isFunction( maybeFunc: unknown ): maybeFunc is () => void {
+	return typeof maybeFunc === 'function';
+}
+
 /**
- * Whether the argument is a function.
  *
- * @param {*} maybeFunc The argument to check.
- * @return {boolean} True if the argument is a function, false otherwise.
+ * The DropdownMenu displays a list of actions (each contained in a MenuItem,
+ * MenuItemsChoice, or MenuGroup) in a compact way. It appears in a Popover
+ * after the user has interacted with an element (a button or icon) or when
+ * they perform a specific action.
+ *
+ * Render a Dropdown Menu with a set of controls:
+ *
+ * ```jsx
+ * import { DropdownMenu } from '@wordpress/components';
+ * import {
+ * 	more,
+ * 	arrowLeft,
+ * 	arrowRight,
+ * 	arrowUp,
+ * 	arrowDown,
+ * } from '@wordpress/icons';
+ *
+ * const MyDropdownMenu = () => (
+ * 	<DropdownMenu
+ * 		icon={ more }
+ * 		label="Select a direction"
+ * 		controls={ [
+ * 			{
+ * 				title: 'Up',
+ * 				icon: arrowUp,
+ * 				onClick: () => console.log( 'up' ),
+ * 			},
+ * 			{
+ * 				title: 'Right',
+ * 				icon: arrowRight,
+ * 				onClick: () => console.log( 'right' ),
+ * 			},
+ * 			{
+ * 				title: 'Down',
+ * 				icon: arrowDown,
+ * 				onClick: () => console.log( 'down' ),
+ * 			},
+ * 			{
+ * 				title: 'Left',
+ * 				icon: arrowLeft,
+ * 				onClick: () => console.log( 'left' ),
+ * 			},
+ * 		] }
+ * 	/>
+ * );
+ * ```
+ *
+ * Alternatively, specify a `children` function which returns elements valid for
+ * use in a DropdownMenu: `MenuItem`, `MenuItemsChoice`, or `MenuGroup`.
+ *
+ * ```jsx
+ * 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 } ) => (
+ * 			<>
+ * 				<MenuGroup>
+ * 					<MenuItem icon={ arrowUp } onClick={ onClose }>
+ * 						Move Up
+ * 					</MenuItem>
+ * 					<MenuItem icon={ arrowDown } onClick={ onClose }>
+ * 						Move Down
+ * 					</MenuItem>
+ * 				</MenuGroup>
+ * 				<MenuGroup>
+ * 					<MenuItem icon={ trash } onClick={ onClose }>
+ * 						Remove
+ * 					</MenuItem>
+ * 				</MenuGroup>
+ * 			</>
+ * 		) }
+ * 	</DropdownMenu>
+ * );
+ * ```
+ *
  */
-function isFunction( maybeFunc ) {
-	return typeof maybeFunc === 'function';
-}
 
-function DropdownMenu( dropdownMenuProps ) {
+function DropdownMenu( dropdownMenuProps: DropdownMenuProps ) {
 	const {
 		children,
 		className,
@@ -62,13 +139,18 @@ function DropdownMenu( dropdownMenuProps ) {
 	}
 
 	// Normalize controls to nested array of objects (sets of controls)
-	let controlSets;
+	let controlSets: DropdownOption[][];
 	if ( controls?.length ) {
+		// @ts-expect-error The check below is needed because `DropdownMenus`
+		// rendered by `ToolBarGroup` receive controls as a nested array.
 		controlSets = controls;
 		if ( ! Array.isArray( controlSets[ 0 ] ) ) {
-			controlSets = [ controlSets ];
+			// This is not ideal, but at this point we know that `controls` is
+			// not a nested array, even if TypeScript doesn't.
+			controlSets = [ controls as DropdownOption[] ];
 		}
 	}
+
 	const mergedPopoverProps = mergeProps(
 		{
 			className: 'components-dropdown-menu__popover',
@@ -81,7 +163,7 @@ function DropdownMenu( dropdownMenuProps ) {
 			className={ classnames( 'components-dropdown-menu', className ) }
 			popoverProps={ mergedPopoverProps }
 			renderToggle={ ( { isOpen, onToggle } ) => {
-				const openOnArrowDown = ( event ) => {
+				const openOnArrowDown = ( event: React.KeyboardEvent ) => {
 					if ( disableOpenOnArrowDown ) {
 						return;
 					}
@@ -110,18 +192,22 @@ function DropdownMenu( dropdownMenuProps ) {
 					<Toggle
 						{ ...mergedToggleProps }
 						icon={ icon }
-						onClick={ ( event ) => {
-							onToggle( event );
-							if ( mergedToggleProps.onClick ) {
-								mergedToggleProps.onClick( event );
-							}
-						} }
-						onKeyDown={ ( event ) => {
-							openOnArrowDown( event );
-							if ( mergedToggleProps.onKeyDown ) {
-								mergedToggleProps.onKeyDown( event );
-							}
-						} }
+						onClick={
+							( ( event ) => {
+								onToggle();
+								if ( mergedToggleProps.onClick ) {
+									mergedToggleProps.onClick( event );
+								}
+							} ) as React.MouseEventHandler< HTMLButtonElement >
+						}
+						onKeyDown={
+							( ( event ) => {
+								openOnArrowDown( event );
+								if ( mergedToggleProps.onKeyDown ) {
+									mergedToggleProps.onKeyDown( event );
+								}
+							} ) as React.KeyboardEventHandler< HTMLButtonElement >
+						}
 						aria-haspopup="true"
 						aria-expanded={ isOpen }
 						label={ label }

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

@@ -1,8 +1,13 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
 /**
  * Internal dependencies
  */
-import DropdownMenu from '../';
-import { MenuGroup, MenuItem } from '../../';
+import DropdownMenu from '..';
+import MenuItem from '../../menu-item';
+import MenuGroup from '../../menu-group';
 
 /**
  * WordPress dependencies
@@ -16,37 +21,24 @@ import {
 	trash,
 } from '@wordpress/icons';
 
-export default {
+const meta: ComponentMeta< typeof DropdownMenu > = {
 	title: 'Components/DropdownMenu',
 	component: DropdownMenu,
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
 	argTypes: {
-		className: { control: { type: 'text' } },
-		children: { control: { type: null } },
-		disableOpenOnArrowDown: { control: { type: 'boolean' } },
 		icon: {
 			options: [ 'menu', 'chevronDown', 'more' ],
 			mapping: { menu, chevronDown, more },
 			control: { type: 'select' },
 		},
-		menuProps: {
-			control: { type: 'object' },
-		},
-		noIcons: { control: { type: 'boolean' } },
-		popoverProps: {
-			control: { type: 'object' },
-		},
-		text: { control: { type: 'text' } },
-		toggleProps: {
-			control: { type: 'object' },
-		},
-	},
-	parameters: {
-		controls: { expanded: true },
-		docs: { source: { state: 'open' } },
 	},
 };
+export default meta;
 
-const Template = ( props ) => (
+const Template: ComponentStory< typeof DropdownMenu > = ( props ) => (
 	<div style={ { height: 150 } }>
 		<DropdownMenu { ...props } />
 	</div>

package/src/dropdown-menu/test/{index.js → index.tsx}

@@ -12,19 +12,19 @@ import { arrowLeft, arrowRight, arrowUp, arrowDown } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
-import DropdownMenu from '../';
-import { MenuItem } from '../../';
+import DropdownMenu from '..';
+import MenuItem from '../../menu-item';
 
 describe( 'DropdownMenu', () => {
 	it( 'should not render when neither controls nor children are assigned', () => {
-		render( <DropdownMenu /> );
+		render( <DropdownMenu label="Open dropdown" /> );
 
 		// The button toggle should not even be rendered
 		expect( screen.queryByRole( 'button' ) ).not.toBeInTheDocument();
 	} );
 
 	it( 'should not render when controls are empty and children is not specified', () => {
-		render( <DropdownMenu controls={ [] } /> );
+		render( <DropdownMenu label="Open dropdown" controls={ [] } /> );
 
 		// The button toggle should not even be rendered
 		expect( screen.queryByRole( 'button' ) ).not.toBeInTheDocument();
@@ -56,7 +56,7 @@ describe( 'DropdownMenu', () => {
 			},
 		];
 
-		render( <DropdownMenu controls={ controls } /> );
+		render( <DropdownMenu label="Open dropdown" controls={ controls } /> );
 
 		// Move focus on the toggle button
 		await user.tab();
@@ -78,6 +78,7 @@ describe( 'DropdownMenu', () => {
 
 		render(
 			<DropdownMenu
+				label="Open dropdown"
 				children={ ( { onClose } ) => <MenuItem onClick={ onClose } /> }
 			/>
 		);