@wordpress/components 21.3.0 → 22.1.0

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/external-link/index.tsx

@@ -38,22 +38,30 @@ function UnforwardedExternalLink(
 		),
 	].join( ' ' );
 	const classes = classnames( 'components-external-link', className );
-	/* Anchor links are percieved as external links.
+	/* Anchor links are perceived as external links.
 	This constant helps check for on page anchor links,
 	to prevent them from being opened in the editor. */
 	const isInternalAnchor = !! href?.startsWith( '#' );
 
+	const onClickHandler = (
+		event: React.MouseEvent< HTMLAnchorElement, MouseEvent >
+	) => {
+		if ( isInternalAnchor ) {
+			event.preventDefault();
+		}
+
+		if ( props.onClick ) {
+			props.onClick( event );
+		}
+	};
+
 	return (
 		/* eslint-disable react/jsx-no-target-blank */
 		<a
 			{ ...additionalProps }
 			className={ classes }
 			href={ href }
-			onClick={
-				isInternalAnchor
-					? ( event ) => event.preventDefault()
-					: undefined
-			}
+			onClick={ onClickHandler }
 			target="_blank"
 			rel={ optimizedRel }
 			ref={ ref }

package/src/external-link/test/index.tsx

@@ -0,0 +1,106 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+/**
+ * Internal dependencies
+ */
+import { ExternalLink } from '..';
+
+const setupUser = () =>
+	userEvent.setup( {
+		advanceTimers: jest.advanceTimersByTime,
+	} );
+
+describe( 'ExternalLink', () => {
+	test( 'should call function passed in onClick handler when clicking the link', async () => {
+		const user = setupUser();
+		const onClickMock = jest.fn();
+
+		render(
+			<ExternalLink href="https://wordpress.org" onClick={ onClickMock }>
+				WordPress.org
+			</ExternalLink>
+		);
+
+		const link = screen.getByRole( 'link', {
+			name: 'WordPress.org (opens in a new tab)',
+		} );
+
+		await user.click( link );
+
+		expect( onClickMock ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	test( 'should prevent default action when clicking an internal anchor link without passing onClick prop', async () => {
+		const user = setupUser();
+
+		render(
+			<ExternalLink href="#test">I&apos;m an anchor link!</ExternalLink>
+		);
+
+		const link = screen.getByRole( 'link', {
+			name: "I'm an anchor link! (opens in a new tab)",
+		} );
+
+		// We are using this approach so we can test the defaultPrevented
+		// without passing an onClick prop to the component.
+		const onClickMock = jest.fn();
+		link.onclick = onClickMock;
+
+		await user.click( link );
+		expect( onClickMock ).toHaveBeenCalledTimes( 1 );
+		expect( onClickMock ).toHaveBeenLastCalledWith(
+			expect.objectContaining( { defaultPrevented: true } )
+		);
+	} );
+
+	test( 'should call function passed in onClick handler and prevent default action when clicking an internal anchor link', async () => {
+		const user = setupUser();
+		const onClickMock = jest.fn();
+
+		render(
+			<ExternalLink href="#test" onClick={ onClickMock }>
+				I&apos;m an anchor link!
+			</ExternalLink>
+		);
+
+		const link = screen.getByRole( 'link', {
+			name: "I'm an anchor link! (opens in a new tab)",
+		} );
+
+		await user.click( link );
+		expect( onClickMock ).toHaveBeenCalledTimes( 1 );
+		expect( onClickMock ).toHaveBeenLastCalledWith(
+			expect.objectContaining( { defaultPrevented: true } )
+		);
+	} );
+
+	test( 'should not prevent default action when clicking a non anchor link without passing onClick prop', async () => {
+		const user = setupUser();
+
+		render(
+			<ExternalLink href="https://wordpress.org">
+				I&apos;m not an anchor link!
+			</ExternalLink>
+		);
+
+		const link = screen.getByRole( 'link', {
+			name: "I'm not an anchor link! (opens in a new tab)",
+		} );
+
+		// We are using this approach so we can test the defaultPrevented
+		// without passing an onClick prop to the component.
+		const onClickMock = jest.fn();
+		link.onclick = onClickMock;
+
+		await user.click( link );
+
+		expect( onClickMock ).toHaveBeenCalledTimes( 1 );
+		expect( onClickMock ).toHaveBeenLastCalledWith(
+			expect.objectContaining( { defaultPrevented: false } )
+		);
+	} );
+} );

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,
 	] );

package/src/flex/test/index.tsx

@@ -10,20 +10,25 @@ import { View } from '../../view';
 import { Flex, FlexBlock, FlexItem } from '../';
 
 describe( 'props', () => {
-	beforeEach( () => {
+	test( 'should render correctly', () => {
 		render(
 			<Flex data-testid="base-flex">
 				<FlexItem>Item</FlexItem>
 				<FlexBlock>Item</FlexBlock>
 			</Flex>
 		);
-	} );
 
-	test( 'should render correctly', () => {
 		expect( screen.getByTestId( 'base-flex' ) ).toMatchSnapshot();
 	} );
 
 	test( 'should render + wrap non Flex children', () => {
+		render(
+			<Flex data-testid="base-flex">
+				<FlexItem>Item</FlexItem>
+				<FlexBlock>Item</FlexBlock>
+			</Flex>
+		);
+
 		render(
 			<Flex data-testid="flex">
 				<FlexItem>Item</FlexItem>
@@ -39,6 +44,13 @@ describe( 'props', () => {
 	} );
 
 	test( 'should render align', () => {
+		render(
+			<Flex data-testid="base-flex">
+				<FlexItem>Item</FlexItem>
+				<FlexBlock>Item</FlexBlock>
+			</Flex>
+		);
+
 		render(
 			<Flex align="flex-start" data-testid="flex">
 				<FlexItem>Item</FlexItem>
@@ -51,6 +63,13 @@ describe( 'props', () => {
 	} );
 
 	test( 'should render justify', () => {
+		render(
+			<Flex data-testid="base-flex">
+				<FlexItem>Item</FlexItem>
+				<FlexBlock>Item</FlexBlock>
+			</Flex>
+		);
+
 		render(
 			<Flex justify="flex-start" data-testid="flex">
 				<FlexItem>Item</FlexItem>
@@ -63,6 +82,13 @@ describe( 'props', () => {
 	} );
 
 	test( 'should render spacing', () => {
+		render(
+			<Flex data-testid="base-flex">
+				<FlexItem>Item</FlexItem>
+				<FlexBlock>Item</FlexBlock>
+			</Flex>
+		);
+
 		render(
 			<>
 				<Flex>

package/src/focal-point-picker/focal-point.tsx

@@ -1,12 +1,7 @@
 /**
  * Internal dependencies
  */
-import {
-	FocalPointWrapper,
-	PointerIconPathFill,
-	PointerIconPathOutline,
-	PointerIconSVG,
-} from './styles/focal-point-style';
+import { PointerCircle } from './styles/focal-point-style';
 
 /**
  * External dependencies
@@ -26,22 +21,5 @@ export default function FocalPoint( {
 
 	const style = { left, top };
 
-	return (
-		<FocalPointWrapper { ...props } className={ classes } style={ style }>
-			<PointerIconSVG
-				className="components-focal-point-picker__icon"
-				xmlns="http://www.w3.org/2000/svg"
-				viewBox="0 0 30 30"
-			>
-				<PointerIconPathOutline
-					className="components-focal-point-picker__icon-outline"
-					d="M15 1C7.3 1 1 7.3 1 15s6.3 14 14 14 14-6.3 14-14S22.7 1 15 1zm0 22c-4.4 0-8-3.6-8-8s3.6-8 8-8 8 3.6 8 8-3.6 8-8 8z"
-				/>
-				<PointerIconPathFill
-					className="components-focal-point-picker__icon-fill"
-					d="M15 3C8.4 3 3 8.4 3 15s5.4 12 12 12 12-5.4 12-12S21.6 3 15 3zm0 22C9.5 25 5 20.5 5 15S9.5 5 15 5s10 4.5 10 10-4.5 10-10 10z"
-				/>
-			</PointerIconSVG>
-		</FocalPointWrapper>
-	);
+	return <PointerCircle { ...props } className={ classes } style={ style } />;
 }

package/src/focal-point-picker/styles/focal-point-style.ts

@@ -3,45 +3,21 @@
  */
 import styled from '@emotion/styled';
 
-/**
- * WordPress dependencies
- */
-import { Path, SVG } from '@wordpress/primitives';
-
-/**
- * Internal dependencies
- */
-import { COLORS } from '../../utils';
-
-export const FocalPointWrapper = styled.div`
+export const PointerCircle = styled.div`
 	background-color: transparent;
 	cursor: grab;
-	height: 30px;
-	margin: -15px 0 0 -15px;
-	opacity: 0.8;
+	height: 48px;
+	margin: -24px 0 0 -24px;
 	position: absolute;
 	user-select: none;
-	width: 30px;
+	width: 48px;
 	will-change: transform;
 	z-index: 10000;
+	background: rgba( 255, 255, 255, 0.6 );
+	border-radius: 50%;
+	backdrop-filter: blur( 4px );
+	box-shadow: rgb( 0 0 0 / 20% ) 0px 0px 10px;
 
 	${ ( { isDragging }: { isDragging: boolean } ) =>
 		isDragging && 'cursor: grabbing;' }
 `;
-
-export const PointerIconSVG = styled( SVG )`
-	display: block;
-	height: 100%;
-	left: 0;
-	position: absolute;
-	top: 0;
-	width: 100%;
-`;
-
-export const PointerIconPathOutline = styled( Path )`
-	fill: white;
-`;
-
-export const PointerIconPathFill = styled( Path )`
-	fill: ${ COLORS.ui.theme };
-`;

package/src/focusable-iframe/index.js

@@ -9,7 +9,6 @@ import deprecated from '@wordpress/deprecated';
  * @param {import('react').Ref<HTMLIFrameElement>} props.iframeRef
  */
 export default function FocusableIframe( { iframeRef, ...props } ) {
-	// @ts-expect-error: Return type for useFocusableIframe() is incorrect.
 	const ref = useMergeRefs( [ iframeRef, useFocusableIframe() ] );
 	deprecated( 'wp.components.FocusableIframe', {
 		since: '5.9',