@wordpress/components 26.0.1-next.5a1d1283.0 → 26.0.2

package/src/confirm-dialog/component.tsx

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import type { ForwardedRef, KeyboardEvent } from 'react';
-
 /**
  * WordPress dependencies
  */
@@ -13,9 +8,9 @@ import { useCallback, useEffect, useRef, useState } from '@wordpress/element';
  * Internal dependencies
  */
 import Modal from '../modal';
-import type { OwnProps, DialogInputEvent } from './types';
-import type { WordPressComponentProps } from '../ui/context';
-import { useContextSystem, contextConnect } from '../ui/context';
+import type { ConfirmDialogProps, DialogInputEvent } from './types';
+import type { WordPressComponentProps } from '../context';
+import { useContextSystem, contextConnect } from '../context';
 import { Flex } from '../flex';
 import Button from '../button';
 import { Text } from '../text';
@@ -23,10 +18,10 @@ import { VStack } from '../v-stack';
 import * as styles from './styles';
 import { useCx } from '../utils/hooks/use-cx';
 
-function ConfirmDialog(
-	props: WordPressComponentProps< OwnProps, 'div', false >,
-	forwardedRef: ForwardedRef< any >
-) {
+const UnconnectedConfirmDialog = (
+	props: WordPressComponentProps< ConfirmDialogProps, 'div', false >,
+	forwardedRef: React.ForwardedRef< any >
+) => {
 	const {
 		isOpen: isOpenProp,
 		onConfirm,
@@ -67,7 +62,7 @@ function ConfirmDialog(
 	);
 
 	const handleEnter = useCallback(
-		( event: KeyboardEvent< HTMLDivElement > ) => {
+		( event: React.KeyboardEvent< HTMLDivElement > ) => {
 			// Avoid triggering the 'confirm' action when a button is focused,
 			// as this can cause a double submission.
 			const isConfirmOrCancelButton =
@@ -101,6 +96,7 @@ function ConfirmDialog(
 						<Text>{ children }</Text>
 						<Flex direction="row" justify="flex-end">
 							<Button
+								__next40pxDefaultSize
 								ref={ cancelButtonRef }
 								variant="tertiary"
 								onClick={ handleEvent( onCancel ) }
@@ -108,6 +104,7 @@ function ConfirmDialog(
 								{ cancelLabel }
 							</Button>
 							<Button
+								__next40pxDefaultSize
 								ref={ confirmButtonRef }
 								variant="primary"
 								onClick={ handleEvent( onConfirm ) }
@@ -120,6 +117,77 @@ function ConfirmDialog(
 			) }
 		</>
 	);
-}
+};
 
-export default contextConnect( ConfirmDialog, 'ConfirmDialog' );
+/**
+ * `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).
+ *
+ * `ConfirmDialog` has two main implicit modes: controlled and uncontrolled.
+ *
+ * UnControlled:
+ *
+ * Allows the component to be used standalone, just by declaring it as part of another React's component render method:
+ * -   It will be automatically open (displayed) upon mounting;
+ * -   It will be automatically closed when clicking the _cancel_ button, by pressing the `ESC` key, or by clicking outside the dialog focus (i.e, the overlay);
+ * -   `onCancel` is not mandatory but can be passed. Even if passed, the dialog will still be able to close itself.
+ *
+ * Activating this mode is as simple as omitting the `isOpen` prop. The only mandatory prop, in this case, is the `onConfirm` callback. The message is passed as the `children`. You can pass any JSX you'd like, which allows to further format the message or include sub-component if you'd like:
+ *
+ * ```jsx
+ * import { __experimentalConfirmDialog as ConfirmDialog } from '@wordpress/components';
+ *
+ * function Example() {
+ * 	return (
+ * 		<ConfirmDialog onConfirm={ () => console.debug( ' Confirmed! ' ) }>
+ * 			Are you sure? <strong>This action cannot be undone!</strong>
+ * 		</ConfirmDialog>
+ * 	);
+ * }
+ * ```
+ *
+ *
+ * Controlled mode:
+ *  Let the parent component control when the dialog is open/closed. It's activated when a
+ * boolean value is passed to `isOpen`:
+ * -   It will not be automatically closed. You need to let it know when to open/close by updating the value of the `isOpen` prop;
+ * -   Both `onConfirm` and the `onCancel` callbacks are mandatory props in this mode;
+ * -   You'll want to update the state that controls `isOpen` by updating it from the `onCancel` and `onConfirm` callbacks.
+ *
+ *```jsx
+ * import { __experimentalConfirmDialog as ConfirmDialog } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * function Example() {
+ * 	const [ isOpen, setIsOpen ] = useState( true );
+ *
+ * 	const handleConfirm = () => {
+ * 		console.debug( 'Confirmed!' );
+ * 		setIsOpen( false );
+ * 	};
+ *
+ * 	const handleCancel = () => {
+ * 		console.debug( 'Cancelled!' );
+ * 		setIsOpen( false );
+ * 	};
+ *
+ * 	return (
+ * 		<ConfirmDialog
+ * 			isOpen={ isOpen }
+ * 			onConfirm={ handleConfirm }
+ * 			onCancel={ handleCancel }
+ * 		>
+ * 			Are you sure? <strong>This action cannot be undone!</strong>
+ * 		</ConfirmDialog>
+ * 	);
+ * }
+ * ```
+ */
+export const ConfirmDialog = contextConnect(
+	UnconnectedConfirmDialog,
+	'ConfirmDialog'
+);
+export default ConfirmDialog;

package/src/confirm-dialog/stories/{index.story.js → index.story.tsx}

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryFn } from '@storybook/react';
+
 /**
  * WordPress dependencies
  */
@@ -7,47 +12,41 @@ import { useState } from '@wordpress/element';
  * Internal dependencies
  */
 import Button from '../../button';
-import { ConfirmDialog } from '..';
+import { ConfirmDialog } from '../component';
 
-const meta = {
+const meta: Meta< typeof ConfirmDialog > = {
 	component: ConfirmDialog,
 	title: 'Components (Experimental)/ConfirmDialog',
 	argTypes: {
-		children: {
-			control: { type: 'text' },
-		},
-		confirmButtonText: {
-			control: { type: 'text' },
-		},
-		cancelButtonText: {
-			control: { type: 'text' },
-		},
 		isOpen: {
 			control: { type: null },
 		},
-		onConfirm: { action: 'onConfirm' },
-		onCancel: { action: 'onCancel' },
-	},
-	args: {
-		children: 'Would you like to privately publish the post now?',
 	},
 	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: {
+			expanded: true,
+		},
 		docs: { canvas: { sourceState: 'shown' } },
 	},
 };
 
 export default meta;
 
-const Template = ( { onConfirm, onCancel, ...args } ) => {
+const Template: StoryFn< typeof ConfirmDialog > = ( {
+	onConfirm,
+	onCancel,
+	...args
+} ) => {
 	const [ isOpen, setIsOpen ] = useState( false );
 
-	const handleConfirm = ( ...confirmArgs ) => {
-		onConfirm( ...confirmArgs );
+	const handleConfirm: typeof onConfirm = ( confirmArgs ) => {
+		onConfirm( confirmArgs );
 		setIsOpen( false );
 	};
 
-	const handleCancel = ( ...cancelArgs ) => {
-		onCancel( ...cancelArgs );
+	const handleCancel: typeof onCancel = ( cancelArgs ) => {
+		onCancel?.( cancelArgs );
 		setIsOpen( false );
 	};
 
@@ -70,7 +69,7 @@ const Template = ( { onConfirm, onCancel, ...args } ) => {
 };
 
 // Simplest usage: just declare the component with the required `onConfirm` prop. Note: the `onCancel` prop is optional here, unless you'd like to render the component in Controlled mode (see below)
-export const _default = Template.bind( {} );
+export const Default = Template.bind( {} );
 const _defaultSnippet = `() => {
   const [ isOpen, setIsOpen ] = useState( false );
   const [ confirmVal, setConfirmVal ] = useState('');
@@ -87,30 +86,31 @@ const _defaultSnippet = `() => {
 
   return (
     <>
-    <ConfirmDialog
-      isOpen={ isOpen }
-      onConfirm={ handleConfirm }
-      onCancel={ handleCancel }
-    >
-      Would you like to privately publish the post now?
-    </ConfirmDialog>
-
-    <Heading level={ 1 }>{ confirmVal }</Heading>
-
-    <Button variant="primary" onClick={ () => setIsOpen( true ) }>
-      Open ConfirmDialog
-    </Button>
+      <ConfirmDialog
+        isOpen={ isOpen }
+        onConfirm={ handleConfirm }
+        onCancel={ handleCancel }
+      >
+        Would you like to privately publish the post now?
+      </ConfirmDialog>
+
+      <Heading level={ 1 }>{ confirmVal }</Heading>
+
+      <Button variant="primary" onClick={ () => setIsOpen( true ) }>
+        Open ConfirmDialog
+      </Button>
     </>
-    );
-  };`;
-_default.args = {};
-_default.parameters = {
+  );
+};`;
+Default.args = {
+	children: 'Would you like to privately publish the post now?',
+};
+Default.parameters = {
 	docs: {
 		source: {
 			code: _defaultSnippet,
 			language: 'jsx',
 			type: 'auto',
-			format: 'true',
 		},
 	},
 };
@@ -118,6 +118,7 @@ _default.parameters = {
 // To customize button text, pass the `cancelButtonText` and/or `confirmButtonText` props.
 export const WithCustomButtonLabels = Template.bind( {} );
 WithCustomButtonLabels.args = {
+	...Default.args,
 	cancelButtonText: 'No thanks',
 	confirmButtonText: 'Yes please!',
 };

package/src/confirm-dialog/test/{index.js → index.tsx}

@@ -1,13 +1,7 @@
 /**
  * External dependencies
  */
-import {
-	render,
-	screen,
-	fireEvent,
-	waitForElementToBeRemoved,
-	waitFor,
-} from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
 /**
@@ -119,7 +113,7 @@ describe( 'Confirm', () => {
 				expect( onCancel ).toHaveBeenCalled();
 			} );
 
-			it( 'should be dismissable even if an `onCancel` callback is not provided', async () => {
+			it( 'should be dismissible even if an `onCancel` callback is not provided', async () => {
 				const user = userEvent.setup();
 
 				render(
@@ -137,6 +131,7 @@ describe( 'Confirm', () => {
 			} );
 
 			it( 'should not render if dialog is closed by clicking the overlay, and the `onCancel` callback should be called', async () => {
+				const user = userEvent.setup();
 				const onCancel = jest.fn().mockName( 'onCancel()' );
 
 				render(
@@ -147,11 +142,9 @@ describe( 'Confirm', () => {
 
 				const confirmDialog = screen.getByRole( 'dialog' );
 
-				//The overlay click is handled by detecting an onBlur from the modal frame.
-				// TODO: replace with `@testing-library/user-event`
-				fireEvent.blur( confirmDialog );
-
-				await waitForElementToBeRemoved( confirmDialog );
+				// Disable reason: Semantic queries can’t reach the overlay.
+				// eslint-disable-next-line testing-library/no-node-access
+				await user.click( confirmDialog.parentElement! );
 
 				expect( confirmDialog ).not.toBeInTheDocument();
 				expect( onCancel ).toHaveBeenCalled();
@@ -315,6 +308,7 @@ describe( 'Confirm', () => {
 		} );
 
 		it( 'should call the `onCancel` callback if the overlay is clicked', async () => {
+			const user = userEvent.setup();
 			const onCancel = jest.fn().mockName( 'onCancel()' );
 
 			render(
@@ -329,13 +323,11 @@ describe( 'Confirm', () => {
 
 			const confirmDialog = screen.getByRole( 'dialog' );
 
-			//The overlay click is handled by detecting an onBlur from the modal frame.
-			// TODO: replace with `@testing-library/user-event`
-			fireEvent.blur( confirmDialog );
+			// Disable reason: Semantic queries can’t reach the overlay.
+			// eslint-disable-next-line testing-library/no-node-access
+			await user.click( confirmDialog.parentElement! );
 
-			// Wait for a DOM side effect here, so that the `queueBlurCheck` in the
-			// `useFocusOutside` hook properly executes its timeout task.
-			await waitFor( () => expect( onCancel ).toHaveBeenCalled() );
+			expect( onCancel ).toHaveBeenCalled();
 		} );
 
 		it( 'should call the `onCancel` callback if the `Escape` key is pressed', async () => {

package/src/confirm-dialog/types.ts

@@ -13,21 +13,41 @@ export type DialogInputEvent =
 	| KeyboardEvent< HTMLDivElement >
 	| MouseEvent< HTMLButtonElement >;
 
-type BaseProps = {
+export type ConfirmDialogProps = {
+	/**
+	 * The actual message for the dialog. It's passed as children and any valid `ReactNode` is accepted.
+	 */
 	children: ReactNode;
+	/**
+	 * The callback that's called when the user confirms.
+	 * A confirmation can happen when the `OK` button is clicked or when `Enter` is pressed.
+	 */
 	onConfirm: ( event: DialogInputEvent ) => void;
+	/**
+	 * The optional custom text to display as the confirmation button's label.
+	 */
 	confirmButtonText?: string;
+	/**
+	 * The optional custom text to display as the cancellation button's label.
+	 */
 	cancelButtonText?: string;
-};
-
-type ControlledProps = BaseProps & {
-	onCancel: ( event: DialogInputEvent ) => void;
-	isOpen: boolean;
-};
-
-type UncontrolledProps = BaseProps & {
+	/**
+	 * The callback that's called when the user cancels. A cancellation can happen
+	 * when the `Cancel` button is clicked, when the `ESC` key is pressed, or when
+	 * a click outside of the dialog focus is detected (i.e. in the overlay).
+	 *
+	 * It's not required if `isOpen` is not set (uncontrolled mode), as the component
+	 * will take care of closing itself, but you can still pass a callback if something
+	 * must be done upon cancelling (the component will still close itself in this case).
+	 *
+	 * If `isOpen` is set (controlled mode), then it's required, and you need to set
+	 * the state that defines `isOpen` to `false` as part of this callback if you want the
+	 * dialog to close when the user cancels.
+	 */
 	onCancel?: ( event: DialogInputEvent ) => void;
-	isOpen?: never;
+	/**
+	 * Defines if the dialog is open (displayed) or closed (not rendered/displayed).
+	 * It also implicitly toggles the controlled mode if set or the uncontrolled mode if it's not set.
+	 */
+	isOpen?: boolean;
 };
-
-export type OwnProps = ControlledProps | UncontrolledProps;

package/src/{ui/context → context}/context-connect.ts

@@ -18,7 +18,7 @@ import type { WordPressComponentFromProps } from '.';
 
 type AcceptsTwoArgs<
 	F extends ( ...args: any ) => any,
-	ErrorMessage = never
+	ErrorMessage = never,
 > = Parameters< F >[ 'length' ] extends 2 ? {} : ErrorMessage;
 
 type ContextConnectOptions = {
@@ -34,7 +34,7 @@ type ContextConnectOptions = {
  * @return The connected WordPressComponent
  */
 export function contextConnect<
-	C extends ( props: any, ref: ForwardedRef< any > ) => JSX.Element | null
+	C extends ( props: any, ref: ForwardedRef< any > ) => JSX.Element | null,
 >(
 	Component: C &
 		AcceptsTwoArgs<
@@ -66,7 +66,7 @@ export function contextConnectWithoutRef< P >(
 // component wrappers.
 function _contextConnect<
 	C extends ( props: any, ref: ForwardedRef< any > ) => JSX.Element | null,
-	O extends ContextConnectOptions
+	O extends ContextConnectOptions,
 >(
 	Component: C,
 	namespace: string,
@@ -99,7 +99,7 @@ function _contextConnect<
 	}
 
 	// @ts-expect-error We can't rely on inferred types here because of the
-	// `as` prop polymorphism we're handling in https://github.com/WordPress/gutenberg/blob/9620bae6fef4fde7cc2b7833f416e240207cda29/packages/components/src/ui/context/wordpress-component.ts#L32-L33
+	// `as` prop polymorphism we're handling in https://github.com/WordPress/gutenberg/blob/4f3a11243c365f94892e479bff0b922ccc4ccda3/packages/components/src/context/wordpress-component.ts#L32-L33
 	return Object.assign( WrappedComponent, {
 		[ CONNECT_STATIC_NAMESPACE ]: [ ...new Set( mergedNamespace ) ],
 		displayName: namespace,

package/src/{ui/context → context}/context-system-provider.js

@@ -20,7 +20,7 @@ import warn from '@wordpress/warning';
 /**
  * Internal dependencies
  */
-import { useUpdateEffect } from '../../utils';
+import { useUpdateEffect } from '../utils';
 
 export const ComponentsContext = createContext(
 	/** @type {Record<string, any>} */ ( {} )

package/src/{ui/context → context}/use-context-system.js

@@ -9,7 +9,7 @@ import warn from '@wordpress/warning';
 import { useComponentsContext } from './context-system-provider';
 import { getNamespace, getConnectedNamespace } from './utils';
 import { getStyledClassNameFromKey } from './get-styled-class-name-from-key';
-import { useCx } from '../../utils/hooks/use-cx';
+import { useCx } from '../utils/hooks/use-cx';
 
 /**
  * @template TProps

package/src/{ui/context → context}/wordpress-component.ts

@@ -3,19 +3,24 @@
  */
 import type * as React from 'react';
 
-// Based on https://github.com/reakit/reakit/blob/master/packages/reakit-utils/src/types.ts
+// Based on https://github.com/ariakit/ariakit/blob/reakit/packages/reakit-utils/src/types.ts
 export type WordPressComponentProps<
 	/** Prop types. */
 	P,
 	/** The HTML element to inherit props from. */
-	T extends React.ElementType,
+	T extends React.ElementType | null,
 	/** Supports polymorphism through the `as` prop. */
-	IsPolymorphic extends boolean = true
+	IsPolymorphic extends boolean = true,
 > = P &
-	// The `children` prop is being explicitly omitted since it is otherwise implicitly added
-	// by `ComponentPropsWithRef`. The context is that components should require the `children`
-	// prop explicitely when needed (see https://github.com/WordPress/gutenberg/pull/31817).
-	Omit< React.ComponentPropsWithoutRef< T >, 'as' | keyof P | 'children' > &
+	( T extends React.ElementType
+		? // The `children` prop is being explicitly omitted since it is otherwise implicitly added
+		  // by `ComponentPropsWithRef`. The context is that components should require the `children`
+		  // prop explicitly when needed (see https://github.com/WordPress/gutenberg/pull/31817).
+		  Omit<
+				React.ComponentPropsWithoutRef< T >,
+				'as' | keyof P | 'children'
+		  >
+		: {} ) &
 	( IsPolymorphic extends true
 		? {
 				/** The HTML element or React component to render the component as. */
@@ -24,9 +29,9 @@ export type WordPressComponentProps<
 		: {} );
 
 export type WordPressComponent<
-	T extends React.ElementType,
+	T extends React.ElementType | null,
 	O,
-	IsPolymorphic extends boolean
+	IsPolymorphic extends boolean,
 > = {
 	< TT extends React.ElementType >(
 		props: WordPressComponentProps< O, TT, IsPolymorphic > &
@@ -49,7 +54,7 @@ export type WordPressComponent<
 
 export type WordPressComponentFromProps<
 	Props,
-	ForwardsRef extends boolean = true
+	ForwardsRef extends boolean = true,
 > = Props extends WordPressComponentProps< infer P, infer T, infer I >
 	? WordPressComponent<
 			T,

package/src/custom-gradient-picker/gradient-bar/control-points.tsx

@@ -34,7 +34,7 @@ import {
 	MINIMUM_SIGNIFICANT_MOVE,
 	KEYBOARD_CONTROL_POINT_VARIATION,
 } from './constants';
-import type { WordPressComponentProps } from '../../ui/context';
+import type { WordPressComponentProps } from '../../context';
 import type {
 	ControlPointButtonProps,
 	ControlPointMoveState,
@@ -42,6 +42,7 @@ import type {
 	InsertPointProps,
 } from '../types';
 import type { CustomColorPickerDropdownProps } from '../../color-palette/types';
+import DropdownContentWrapper from '../../dropdown/dropdown-content-wrapper';
 
 function ControlPointButton( {
 	isOpen,
@@ -93,7 +94,11 @@ function GradientColorPickerDropdown( {
 			( {
 				placement: 'bottom',
 				offset: 8,
-			} as const ),
+				// Disabling resize as it would otherwise cause the popover to show
+				// scrollbars while dragging the color picker's handle close to the
+				// popover edge.
+				resize: false,
+			} ) as const,
 		[]
 	);
 
@@ -271,7 +276,7 @@ function ControlPoints( {
 								/>
 							) }
 							renderContent={ ( { onClose } ) => (
-								<>
+								<DropdownContentWrapper paddingSize="none">
 									<ColorPicker
 										enableAlpha={ ! disableAlpha }
 										color={ point.color }
@@ -311,7 +316,7 @@ function ControlPoints( {
 												</Button>
 											</HStack>
 										) }
-								</>
+								</DropdownContentWrapper>
 							) }
 							style={ {
 								left: `${ point.position }%`,
@@ -360,29 +365,31 @@ function InsertPoint( {
 				/>
 			) }
 			renderContent={ () => (
-				<ColorPicker
-					enableAlpha={ ! disableAlpha }
-					onChange={ ( color ) => {
-						if ( ! alreadyInsertedPoint ) {
-							onChange(
-								addControlPoint(
-									controlPoints,
-									insertPosition,
-									colord( color ).toRgbString()
-								)
-							);
-							setAlreadyInsertedPoint( true );
-						} else {
-							onChange(
-								updateControlPointColorByPosition(
-									controlPoints,
-									insertPosition,
-									colord( color ).toRgbString()
-								)
-							);
-						}
-					} }
-				/>
+				<DropdownContentWrapper paddingSize="none">
+					<ColorPicker
+						enableAlpha={ ! disableAlpha }
+						onChange={ ( color ) => {
+							if ( ! alreadyInsertedPoint ) {
+								onChange(
+									addControlPoint(
+										controlPoints,
+										insertPosition,
+										colord( color ).toRgbString()
+									)
+								);
+								setAlreadyInsertedPoint( true );
+							} else {
+								onChange(
+									updateControlPointColorByPosition(
+										controlPoints,
+										insertPosition,
+										colord( color ).toRgbString()
+									)
+								);
+							}
+						} }
+					/>
+				</DropdownContentWrapper>
 			) }
 			style={
 				insertPosition !== null

package/src/custom-gradient-picker/gradient-bar/test/utils.ts

@@ -13,7 +13,7 @@ describe( 'getHorizontalRelativeGradientPosition', () => {
 				( {
 					x: 0,
 					width: 1000,
-				} as DOMRect )
+				} ) as DOMRect
 		);
 
 		const containerElement = document.createElement( 'div' );
@@ -31,7 +31,7 @@ describe( 'getHorizontalRelativeGradientPosition', () => {
 				( {
 					x: 50,
 					width: 1000,
-				} as DOMRect )
+				} ) as DOMRect
 		);
 
 		const containerElement = document.createElement( 'div' );
@@ -49,7 +49,7 @@ describe( 'getHorizontalRelativeGradientPosition', () => {
 				( {
 					x: 0,
 					width: 1000,
-				} as DOMRect )
+				} ) as DOMRect
 		);
 
 		const containerElement = document.createElement( 'div' );
@@ -68,7 +68,7 @@ describe( 'getHorizontalRelativeGradientPosition', () => {
 				( {
 					x: 50,
 					width: 1000,
-				} as DOMRect )
+				} ) as DOMRect
 		);
 		const containerElement = document.createElement( 'div' );
 
@@ -86,7 +86,7 @@ describe( 'getHorizontalRelativeGradientPosition', () => {
 				( {
 					x: 50,
 					width: 1000,
-				} as DOMRect )
+				} ) as DOMRect
 		);
 
 		const containerElement = document.createElement( 'div' );