@wordpress/components 22.0.0 → 22.1.0

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.js

@@ -3,6 +3,7 @@
  *
  * @property {import('./types').IconKey} icon        Icon name
  * @property {string}                    [className] Class name
+ * @property {number}                    [size]      Size of the icon
  */
 /** @typedef {import('react').ComponentPropsWithoutRef<'span'> & OwnProps} Props */
 
@@ -10,7 +11,8 @@
  * @param {Props} props
  * @return {JSX.Element} Element
  */
-function Dashicon( { icon, className, ...extraProps } ) {
+
+function Dashicon( { icon, className, size = 20, style = {}, ...extraProps } ) {
 	const iconClass = [
 		'dashicon',
 		'dashicons',
@@ -20,7 +22,24 @@ function Dashicon( { icon, className, ...extraProps } ) {
 		.filter( Boolean )
 		.join( ' ' );
 
-	return <span className={ iconClass } { ...extraProps } />;
+	// 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/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/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/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

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

@@ -1,38 +1,64 @@
+/**
+ * External dependencies
+ */
+import type { DragEvent } from 'react';
+
 /**
  * WordPress dependencies
  */
 import { throttle } from '@wordpress/compose';
 import { useEffect, useRef } from '@wordpress/element';
 
+/**
+ * Internal dependencies
+ */
+import type { DraggableProps } from './types';
+
 const dragImageClass = 'components-draggable__invisible-drag-image';
 const cloneWrapperClass = 'components-draggable__clone';
 const clonePadding = 0;
 const bodyClass = 'is-dragging-components-draggable';
 
 /**
- * @typedef RenderProp
- * @property {(event: import('react').DragEvent) => void} onDraggableStart `onDragStart` handler.
- * @property {(event: import('react').DragEvent) => void} onDraggableEnd   `onDragEnd` handler.
+ * `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.
+ *
+ * ```jsx
+ * import { Draggable, Panel, PanelBody } from '@wordpress/components';
+ * import { Icon, more } from '@wordpress/icons';
+ *
+ * const MyDraggable = () => (
+ *   <div id="draggable-panel">
+ *     <Panel header="Draggable panel">
+ *       <PanelBody>
+ *         <Draggable elementId="draggable-panel" transferData={ {} }>
+ *           { ( { onDraggableStart, onDraggableEnd } ) => (
+ *             <div
+ *               className="example-drag-handle"
+ *               draggable
+ *               onDragStart={ onDraggableStart }
+ *               onDragEnd={ onDraggableEnd }
+ *             >
+ *               <Icon icon={ more } />
+ *             </div>
+ *           ) }
+ *         </Draggable>
+ *       </PanelBody>
+ *     </Panel>
+ *   </div>
+ * );
+ * ```
  */
-
-/**
- * @typedef Props
- * @property {(props: RenderProp) => JSX.Element | null}  children                         Children.
- * @property {(event: import('react').DragEvent) => void} [onDragStart]                    Callback when dragging starts.
- * @property {(event: import('react').DragEvent) => void} [onDragOver]                     Callback when dragging happens over the document.
- * @property {(event: import('react').DragEvent) => void} [onDragEnd]                      Callback when dragging ends.
- * @property {string}                                     [cloneClassname]                 Classname for the cloned element.
- * @property {string}                                     [elementId]                      ID for the element.
- * @property {any}                                        [transferData]                   Transfer data for the drag event.
- * @property {string}                                     [__experimentalTransferDataType] The transfer data type to set.
- * @property {import('react').ReactNode}                  __experimentalDragComponent      Component to show when dragging.
- */
-
-/**
- * @param {Props} props
- * @return {JSX.Element} A draggable component.
- */
-export default function Draggable( {
+export function Draggable( {
 	children,
 	onDragStart,
 	onDragOver,
@@ -42,17 +68,16 @@ export default function Draggable( {
 	transferData,
 	__experimentalTransferDataType: transferDataType = 'text',
 	__experimentalDragComponent: dragComponent,
-} ) {
-	/** @type {import('react').MutableRefObject<HTMLDivElement | null>} */
-	const dragComponentRef = useRef( null );
+}: DraggableProps ) {
+	const dragComponentRef = useRef< HTMLDivElement >( null );
 	const cleanup = useRef( () => {} );
 
 	/**
 	 * Removes the element clone, resets cursor, and removes drag listener.
 	 *
-	 * @param {import('react').DragEvent} event The non-custom DragEvent.
+	 * @param  event The non-custom DragEvent.
 	 */
-	function end( event ) {
+	function end( event: DragEvent ) {
 		event.preventDefault();
 		cleanup.current();
 
@@ -69,11 +94,10 @@ export default function Draggable( {
 	 * - Sets transfer data.
 	 * - Adds dragover listener.
 	 *
-	 * @param {import('react').DragEvent} event The non-custom DragEvent.
+	 * @param  event The non-custom DragEvent.
 	 */
-	function start( event ) {
-		// @ts-ignore We know that ownerDocument does exist on an Element
-		const { ownerDocument } = event.target;
+	function start( event: DragEvent ) {
+		const { ownerDocument } = event.target as HTMLElement;
 
 		event.dataTransfer.setData(
 			transferDataType,
@@ -82,8 +106,8 @@ export default function Draggable( {
 
 		const cloneWrapper = ownerDocument.createElement( 'div' );
 		// Reset position to 0,0. Natural stacking order will position this lower, even with a transform otherwise.
-		cloneWrapper.style.top = 0;
-		cloneWrapper.style.left = 0;
+		cloneWrapper.style.top = '0';
+		cloneWrapper.style.left = '0';
 
 		const dragImage = ownerDocument.createElement( 'div' );
 
@@ -119,19 +143,21 @@ export default function Draggable( {
 			// Inject the cloneWrapper into the DOM.
 			ownerDocument.body.appendChild( cloneWrapper );
 		} else {
-			const element = ownerDocument.getElementById( elementId );
+			const element = ownerDocument.getElementById(
+				elementId
+			) as HTMLElement;
 
 			// Prepare element clone and append to element wrapper.
 			const elementRect = element.getBoundingClientRect();
 			const elementWrapper = element.parentNode;
-			const elementTopOffset = parseInt( elementRect.top, 10 );
-			const elementLeftOffset = parseInt( elementRect.left, 10 );
+			const elementTopOffset = elementRect.top;
+			const elementLeftOffset = elementRect.left;
 
 			cloneWrapper.style.width = `${
 				elementRect.width + clonePadding * 2
 			}px`;
 
-			const clone = element.cloneNode( true );
+			const clone = element.cloneNode( true ) as HTMLElement;
 			clone.id = `clone-${ elementId }`;
 
 			// Position clone right over the original element (20px padding).
@@ -140,24 +166,21 @@ export default function Draggable( {
 			cloneWrapper.style.transform = `translate( ${ x }px, ${ y }px )`;
 
 			// Hack: Remove iFrames as it's causing the embeds drag clone to freeze.
-			Array.from( clone.querySelectorAll( 'iframe' ) ).forEach(
-				( child ) => child.parentNode.removeChild( child )
-			);
+			Array.from< HTMLIFrameElement >(
+				clone.querySelectorAll( 'iframe' )
+			).forEach( ( child ) => child.parentNode?.removeChild( child ) );
 
 			cloneWrapper.appendChild( clone );
 
 			// Inject the cloneWrapper into the DOM.
-			elementWrapper.appendChild( cloneWrapper );
+			elementWrapper?.appendChild( cloneWrapper );
 		}
 
 		// Mark the current cursor coordinates.
 		let cursorLeft = event.clientX;
 		let cursorTop = event.clientY;
 
-		/**
-		 * @param {import('react').DragEvent<Element>} e
-		 */
-		function over( e ) {
+		function over( e: DragEvent ) {
 			// Skip doing any work if mouse has not moved.
 			if ( cursorLeft === e.clientX && cursorTop === e.clientY ) {
 				return;
@@ -188,8 +211,7 @@ export default function Draggable( {
 		// https://reactjs.org/docs/events.html#event-pooling
 		event.persist();
 
-		/** @type {number | undefined} */
-		let timerId;
+		let timerId: number | undefined;
 
 		if ( onDragStart ) {
 			timerId = setTimeout( () => onDragStart( event ) );
@@ -239,3 +261,5 @@ export default function Draggable( {
 		</>
 	);
 }
+
+export default Draggable;

package/src/draggable/stories/index.tsx

@@ -0,0 +1,83 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { DragEvent } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+import { Icon, more } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import Draggable from '..';
+
+const meta: ComponentMeta< typeof Draggable > = {
+	component: Draggable,
+	title: 'Components/Draggable',
+	argTypes: {
+		elementId: { control: { type: null } },
+		__experimentalDragComponent: { control: { type: null } },
+	},
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: { expanded: true },
+		docs: { source: { code: '' } },
+	},
+};
+export default meta;
+
+const DefaultTemplate: ComponentStory< typeof Draggable > = ( args ) => {
+	const [ isDragging, setDragging ] = useState( false );
+
+	// Allow for the use of ID in the example.
+	return (
+		<div>
+			<p>Is Dragging? { isDragging ? 'Yes' : 'No!' }</p>
+			<div
+				/* eslint-disable no-restricted-syntax, eslint-comments/disable-enable-pair */
+				id="draggable-example-box"
+				style={ { display: 'inline-flex' } }
+			>
+				<Draggable { ...args } elementId="draggable-example-box">
+					{ ( { onDraggableStart, onDraggableEnd } ) => {
+						const handleOnDragStart = ( event: DragEvent ) => {
+							setDragging( true );
+							onDraggableStart( event );
+						};
+						const handleOnDragEnd = ( event: DragEvent ) => {
+							setDragging( false );
+							onDraggableEnd( event );
+						};
+
+						return (
+							<div
+								onDragStart={ handleOnDragStart }
+								onDragEnd={ handleOnDragEnd }
+								draggable
+								style={ {
+									alignItems: 'center',
+									display: 'flex',
+									justifyContent: 'center',
+									width: 100,
+									height: 100,
+									background: '#ddd',
+								} }
+							>
+								<Icon icon={ more } />
+							</div>
+						);
+					} }
+				</Draggable>
+			</div>
+		</div>
+	);
+};
+
+export const Default: ComponentStory< typeof Draggable > = DefaultTemplate.bind(
+	{}
+);
+Default.args = {};

package/src/draggable/types.ts

@@ -0,0 +1,58 @@
+/**
+ * External dependencies
+ */
+import type { DragEvent, ReactNode } from 'react';
+
+export type DraggableProps = {
+	/**
+	 * Children.
+	 */
+	children: ( props: {
+		/**
+		 * `onDragStart` handler.
+		 */
+		onDraggableStart: ( event: DragEvent ) => void;
+		/**
+		 * `onDragEnd` handler.
+		 */
+		onDraggableEnd: ( event: DragEvent ) => void;
+	} ) => JSX.Element | null;
+	/**
+	 * Classname for the cloned element.
+	 */
+	cloneClassname?: string;
+	/**
+	 * The HTML id of the element to clone on drag
+	 */
+	elementId: string;
+	/**
+	 * A function called when dragging ends. This callback receives the `event`
+	 * object from the `dragend` event as its first parameter.
+	 */
+	onDragEnd?: ( 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.
+	 */
+	onDragOver?: ( event: DragEvent ) => void;
+	/**
+	 * A function called when dragging starts. This callback receives the
+	 * `event` object from the `dragstart` event as its first parameter.
+	 */
+	onDragStart?: ( event: DragEvent ) => void;
+	/**
+	 * Arbitrary data object attached to the drag and drop event.
+	 */
+	transferData: unknown;
+	/**
+	 * The transfer data type to set.
+	 *
+	 * @default 'text'
+	 */
+	__experimentalTransferDataType?: string;
+	/**
+	 * Component to show when dragging.
+	 */
+	__experimentalDragComponent?: ReactNode;
+};

package/src/drop-zone/style.scss

@@ -24,7 +24,7 @@
 	height: 100%;
 	width: 100%;
 	display: flex;
-	background-color: var(--wp-admin-theme-color);
+	background-color: $components-color-accent;
 	align-items: center;
 	justify-content: center;
 	z-index: z-index(".components-drop-zone__content");

package/src/flex/flex/hook.ts

@@ -57,8 +57,6 @@ export function useFlex( props: WordPressComponentProps< FlexProps, 'div' > ) {
 
 	const isColumn =
 		typeof direction === 'string' && !! direction.includes( 'column' );
-	const isReverse =
-		typeof direction === 'string' && direction.includes( 'reverse' );
 
 	const cx = useCx();
 
@@ -87,7 +85,6 @@ export function useFlex( props: WordPressComponentProps< FlexProps, 'div' > ) {
 		expanded,
 		gap,
 		isColumn,
-		isReverse,
 		justify,
 		wrap,
 	] );