@wordpress/components 22.0.0 → 23.0.0

package/src/confirm-dialog/README.md

@@ -4,7 +4,7 @@
 This feature is still experimental. "Experimental" means this is an early implementation subject to drastic and breaking changes.
 </div>
 
-`ConfirmDialog` is built of top of [`Modal`](/packages/components/src/modal/README.md] and displays a confirmation dialog, with _confirm_ and _cancel_ buttons.
+`ConfirmDialog` is built of top of [`Modal`](/packages/components/src/modal/README.md) and displays a confirmation dialog, with _confirm_ and _cancel_ buttons.
 
 The dialog is confirmed by clicking the _confirm_ button or by pressing the `Enter` key. It is cancelled (closed) by clicking the _cancel_ button, by pressing the `ESC` key, or by clicking outside the dialog focus (i.e, the overlay).
 
@@ -44,6 +44,7 @@ Let the parent component control when the dialog is open/closed. It's activated
 
 ```jsx
 import { __experimentalConfirmDialog as ConfirmDialog } from '@wordpress/components';
+import { useState } from '@wordpress/element';
 
 function Example() {
 	const [ isOpen, setIsOpen ] = useState( true );
@@ -72,7 +73,7 @@ function Example() {
 
 ### Unsupported: Multiple instances
 
-Multiple `ConfirmDialog's is an edge case that's currently not officially supported by this component. At the moment, new instances will end up closing the last instance due to the way the `Modal` is implemented.
+Multiple `ConfirmDialog`s is an edge case that's currently not officially supported by this component. At the moment, new instances will end up closing the last instance due to the way the `Modal` is implemented.
 
 ## Custom Types
 

package/src/custom-select-control/README.md

@@ -145,6 +145,20 @@ A handler for onMouseOut events.
 -   Type: `Function`
 -   Required: No
 
+#### onFocus
+
+A handler for onFocus events.
+
+-   Type: `Function`
+-   Required: No
+
+#### onBlur
+
+A handler for onBlur events.
+
+-   Type: `Function`
+-   Required: No
+
 ## Related components
 
 -   Like this component, but implemented using a native `<select>` for when custom styling is not necessary, the `SelectControl` component.

package/src/custom-select-control/index.js

@@ -79,6 +79,9 @@ export default function CustomSelectControl( props ) {
 		value: _selectedItem,
 		onMouseOver,
 		onMouseOut,
+		onFocus,
+		onBlur,
+		__experimentalShowSelectedHint = false,
 	} = props;
 
 	const {
@@ -102,6 +105,16 @@ export default function CustomSelectControl( props ) {
 
 	const [ isFocused, setIsFocused ] = useState( false );
 
+	function handleOnFocus( e ) {
+		setIsFocused( true );
+		onFocus?.( e );
+	}
+
+	function handleOnBlur( e ) {
+		setIsFocused( false );
+		onBlur?.( e );
+	}
+
 	if ( ! __nextUnconstrainedWidth ) {
 		deprecated(
 			'Constrained width styles for wp.components.CustomSelectControl',
@@ -181,8 +194,8 @@ export default function CustomSelectControl( props ) {
 					onMouseOver={ onMouseOver }
 					onMouseOut={ onMouseOut }
 					as="button"
-					onFocus={ () => setIsFocused( true ) }
-					onBlur={ () => setIsFocused( false ) }
+					onFocus={ handleOnFocus }
+					onBlur={ handleOnBlur }
 					selectSize={ size }
 					__next36pxDefaultSize={ __next36pxDefaultSize }
 					{ ...getToggleButtonProps( {
@@ -194,6 +207,12 @@ export default function CustomSelectControl( props ) {
 					} ) }
 				>
 					{ itemToString( selectedItem ) }
+					{ __experimentalShowSelectedHint &&
+						selectedItem.__experimentalHint && (
+							<span className="components-custom-select-control__hint">
+								{ selectedItem.__experimentalHint }
+							</span>
+						) }
 				</SelectControlSelect>
 			</InputBaseWithBackCompatMinWidth>
 			{ /* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions */ }

package/src/custom-select-control/stories/index.js

@@ -8,6 +8,7 @@ export default {
 	component: CustomSelectControl,
 	argTypes: {
 		__next36pxDefaultSize: { control: { type: 'boolean' } },
+		__experimentalShowSelectedHint: { control: { type: 'boolean' } },
 		size: {
 			control: {
 				type: 'radio',

package/src/custom-select-control/style.scss

@@ -9,6 +9,11 @@
 	outline: 0; // focus ring is handled elsewhere
 }
 
+.components-custom-select-control__hint {
+	color: $gray-600;
+	margin-left: 10px;
+}
+
 .components-custom-select-control__menu {
 	// Hide when collapsed.
 	&[aria-hidden="true"] {
@@ -50,7 +55,7 @@
 		background: $gray-300;
 	}
 	.components-custom-select-control__item-hint {
-		color: $gray-700;
+		color: $gray-600;
 		text-align: right;
 		padding-right: $grid-unit-05;
 	}

package/src/custom-select-control/test/index.js

@@ -46,4 +46,43 @@ describe( 'CustomSelectControl', () => {
 
 		expect( onKeyDown ).toHaveBeenCalledTimes( 0 );
 	} );
+
+	it( 'does not show selected hint by default', () => {
+		render(
+			<CustomSelectControl
+				label="Custom select"
+				options={ [
+					{
+						key: 'one',
+						name: 'One',
+						__experimentalHint: 'Hint',
+					},
+				] }
+				__nextUnconstrainedWidth
+			/>
+		);
+		expect(
+			screen.getByRole( 'button', { name: 'Custom select' } )
+		).not.toHaveTextContent( 'Hint' );
+	} );
+
+	it( 'shows selected hint when __experimentalShowSelectedHint is set', () => {
+		render(
+			<CustomSelectControl
+				label="Custom select"
+				options={ [
+					{
+						key: 'one',
+						name: 'One',
+						__experimentalHint: 'Hint',
+					},
+				] }
+				__experimentalShowSelectedHint
+				__nextUnconstrainedWidth
+			/>
+		);
+		expect(
+			screen.getByRole( 'button', { name: 'Custom select' } )
+		).toHaveTextContent( 'Hint' );
+	} );
 } );

package/src/dashicon/index.tsx

@@ -0,0 +1,51 @@
+/**
+ * @typedef OwnProps
+ *
+ * @property {import('./types').IconKey} icon        Icon name
+ * @property {string}                    [className] Class name
+ * @property {number}                    [size]      Size of the icon
+ */
+
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../ui/context';
+import type { DashiconProps } from './types';
+
+function Dashicon( {
+	icon,
+	className,
+	size = 20,
+	style = {},
+	...extraProps
+}: WordPressComponentProps< DashiconProps, 'span', false > ) {
+	const iconClass = [
+		'dashicon',
+		'dashicons',
+		'dashicons-' + icon,
+		className,
+	]
+		.filter( Boolean )
+		.join( ' ' );
+
+	// For retro-compatibility reasons (for example if people are overriding icon size with CSS), we add inline styles just if the size is different to the default
+	const sizeStyles =
+		// using `!=` to catch both 20 and "20"
+		// eslint-disable-next-line eqeqeq
+		20 != size
+			? {
+					fontSize: `${ size }px`,
+					width: `${ size }px`,
+					height: `${ size }px`,
+			  }
+			: {};
+
+	const styles = {
+		...sizeStyles,
+		...style,
+	};
+
+	return <span className={ iconClass } style={ styles } { ...extraProps } />;
+}
+
+export default Dashicon;

package/src/dashicon/types.ts

@@ -1,3 +1,20 @@
+export type DashiconProps = {
+	/**
+	 * The icon name
+	 */
+	icon: IconKey;
+
+	/**
+	 * Class name
+	 */
+	className?: string;
+
+	/**
+	 * Size of the icon
+	 */
+	size?: number;
+};
+
 export type IconKey =
 	| 'admin-appearance'
 	| 'admin-collapse'

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

@@ -16,7 +16,7 @@ describe( 'DatePicker', () => {
 
 		expect(
 			screen.getByRole( 'button', { name: 'May 2, 2022. Selected' } )
-		).not.toBeNull();
+		).toBeInTheDocument();
 	} );
 
 	it( "should highlight today's date when not provided a currentDate", () => {
@@ -27,7 +27,7 @@ describe( 'DatePicker', () => {
 			screen.getByRole( 'button', {
 				name: `${ todayDescription }. Selected`,
 			} )
-		).not.toBeNull();
+		).toBeInTheDocument();
 	} );
 
 	it( 'should call onChange when a day is selected', async () => {

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

@@ -43,14 +43,14 @@ function UnforwardedDateTimePicker(
 	if ( ! __nextRemoveHelpButton ) {
 		deprecated( 'Help button in wp.components.DateTimePicker', {
 			since: '13.4',
-			version: '14.6', // Six months of plugin releases.
+			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: '14.6', // Six months of plugin releases.
+			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.',
 		} );
 	}

package/src/date-time/types.ts

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import type { Moment } from 'moment';
-
 export type TimePickerProps = {
 	/**
 	 * The initial current time the time picker should render.
@@ -30,20 +25,6 @@ export type DatePickerEvent = {
 	date: Date;
 };
 
-export type DatePickerDayProps = {
-	/**
-	 * The day to display.
-	 */
-	day: Moment;
-
-	/**
-	 * List of events to show on this day.
-	 *
-	 * @default []
-	 */
-	events?: DatePickerEvent[];
-};
-
 export type DatePickerProps = {
 	/**
 	 * The current date and time at initialization. Optionally pass in a `null`

package/src/dimension-control/test/__snapshots__/index.test.js.snap

@@ -37,7 +37,6 @@ exports[`DimensionControl rendering renders with custom sizes 1`] = `
   -webkit-box-pack: justify;
   -webkit-justify-content: space-between;
   justify-content: space-between;
-  height: 100%;
   box-sizing: border-box;
   position: relative;
   border-radius: 2px;
@@ -175,7 +174,7 @@ exports[`DimensionControl rendering renders with custom sizes 1`] = `
   position: absolute;
   right: 0;
   top: 0;
-  border-color: #757575;
+  border-color: #949494;
   border-style: solid;
   border-width: 1px;
   padding-left: 2px;
@@ -309,7 +308,6 @@ exports[`DimensionControl rendering renders with defaults 1`] = `
   -webkit-box-pack: justify;
   -webkit-justify-content: space-between;
   justify-content: space-between;
-  height: 100%;
   box-sizing: border-box;
   position: relative;
   border-radius: 2px;
@@ -447,7 +445,7 @@ exports[`DimensionControl rendering renders with defaults 1`] = `
   position: absolute;
   right: 0;
   top: 0;
-  border-color: #757575;
+  border-color: #949494;
   border-style: solid;
   border-width: 1px;
   padding-left: 2px;
@@ -591,7 +589,6 @@ exports[`DimensionControl rendering renders with icon and custom icon label 1`]
   -webkit-box-pack: justify;
   -webkit-justify-content: space-between;
   justify-content: space-between;
-  height: 100%;
   box-sizing: border-box;
   position: relative;
   border-radius: 2px;
@@ -729,7 +726,7 @@ exports[`DimensionControl rendering renders with icon and custom icon label 1`]
   position: absolute;
   right: 0;
   top: 0;
-  border-color: #757575;
+  border-color: #949494;
   border-style: solid;
   border-width: 1px;
   padding-left: 2px;
@@ -885,7 +882,6 @@ exports[`DimensionControl rendering renders with icon and default icon label 1`]
   -webkit-box-pack: justify;
   -webkit-justify-content: space-between;
   justify-content: space-between;
-  height: 100%;
   box-sizing: border-box;
   position: relative;
   border-radius: 2px;
@@ -1023,7 +1019,7 @@ exports[`DimensionControl rendering renders with icon and default icon label 1`]
   position: absolute;
   right: 0;
   top: 0;
-  border-color: #757575;
+  border-color: #949494;
   border-style: solid;
   border-width: 1px;
   padding-left: 2px;

package/src/disabled/test/index.tsx

@@ -18,48 +18,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/divider/test/index.tsx

@@ -9,15 +9,13 @@ import { render, screen } from '@testing-library/react';
 import { Divider } from '..';
 
 describe( 'props', () => {
-	beforeEach( () => {
-		render( <Divider /> );
-	} );
-
 	test( 'should render correctly', () => {
+		render( <Divider /> );
 		expect( screen.getByRole( 'separator' ) ).toMatchSnapshot();
 	} );
 
 	test( 'should render marginStart', () => {
+		render( <Divider /> );
 		render( <Divider marginStart={ 5 } /> );
 
 		const dividers = screen.getAllByRole( 'separator' );
@@ -25,6 +23,7 @@ describe( 'props', () => {
 	} );
 
 	test( 'should render marginEnd', () => {
+		render( <Divider /> );
 		render( <Divider marginEnd={ 5 } /> );
 
 		const dividers = screen.getAllByRole( 'separator' );
@@ -32,6 +31,7 @@ describe( 'props', () => {
 	} );
 
 	test( 'should render margin', () => {
+		render( <Divider /> );
 		render( <Divider margin={ 7 } /> );
 
 		const dividers = screen.getAllByRole( 'separator' );

package/src/draggable/README.md

@@ -1,6 +1,6 @@
 # Draggable
 
-`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.
+`Draggable` is a Component that provides a way to set up a cross-browser (including IE) customizable 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.
 
@@ -8,44 +8,39 @@ Note that the drag handle needs to declare the `draggable="true"` property and b
 
 The component accepts the following props:
 
-### elementId
+### `elementId`: `string`
 
 The HTML id of the element to clone on drag
 
--   Type: `string`
 -   Required: Yes
 
-### transferData
+### `onDragEnd`: `( event: DragEvent ) => void`
 
-Arbitrary data object attached to the drag and drop event.
-
--   Type: `Object`
--   Required: Yes
-
-### onDragStart
-
-A function called when dragging starts. This callback receives the `event` object from the `dragstart` event as its first parameter.
+A function called when dragging ends. This callback receives the `event` object from the `dragend` event as its first parameter.
 
--   Type: `Function`
 -   Required: No
 -   Default: `noop`
 
-### onDragOver
+### `onDragOver`: `( event: DragEvent ) => void`
 
 A function called when the element being dragged is dragged over a valid drop target. This callback receives the `event` object from the `dragover` event as its first parameter.
 
--   Type: `Function`
 -   Required: No
 -   Default: `noop`
 
-### onDragEnd
+### `onDragStart`: `( event: DragEvent ) => void`
 
-A function called when dragging ends. This callback receives the `event` object from the `dragend` event as its first parameter.
+A function called when dragging starts. This callback receives the `event` object from the `dragstart` event as its first parameter.
 
--   Type: `Function`
 -   Required: No
 -   Default: `noop`
 
+### `transferData`: `unknown`
+
+Arbitrary data object attached to the drag and drop event.
+
+-   Required: Yes
+
 ## Usage
 
 ```jsx