Components: Add experimental ConfirmDialog

docs/manifest.json

@@ -779,6 +779,12 @@
 		"markdown_source": "../packages/components/src/combobox-control/README.md",
 		"parent": "components"
 	},
+	{
+		"title": "ConfirmDialog",
+		"slug": "confirm-dialog",
+		"markdown_source": "../packages/components/src/confirm-dialog/README.md",
+		"parent": "components"
+	},
 	{
 		"title": "CustomSelectControl",
 		"slug": "custom-select-control",

packages/components/src/confirm-dialog/README.md

@@ -0,0 +1,102 @@
+# `ConfirmDialog`
+
+<div class="callout callout-alert">
+This feature is still experimental. "Experimental" means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+`ConfirmDialog` displays a confirmation dialog as a `Modal`, with `OK` and `Cancel` buttons. It's confirmed by clicking `OK` or by pressing the `Enter` key. It's cancelled by clicking `Cancel` or by pressing the `ESC` key or clicking outside the dialog focus (i.e, the overlay).
+
+It's built on top of `Modal`, so you can override any of the `Modal` props if you'd like. This also means that it's added as a child of the `body` element in the DOM tree through a React `Portal`, regardless of where it's declared in the React tree.
+
+## Usage
+
+`ConfirmDialog` has two main implicit modes: controlled and uncontrolled.
+
+### Uncontrolled mode
+
+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 automatically close itself when the `x`, `Cancel`, `Confirm` or overlay is clicked;
+  * `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.
+
+```jsx
+import {
+  __experimentalConfirmDialog as ConfirmDialog
+} from '@wordpress/components';
+
+function Example() {
+  return (
+    <ConfirmDialog onConfirm={ () => console.debug(' Confirmed! ') }>
+  )
+}
+```
+
+### 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';
+
+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 }>
+  )
+}
+```
+
+### 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 (more specifically, because of the use of the `onFocusOutside` to detect a blur in order to close it). This will end up automatically cancelling the previous instance, which might or might not be what you want.
+
+Suppose you need to handle multiple confirmations without discarding other instances. In that case, it might be better to have a singleton wrapper component that provides a context-based API to trigger the dialog, keeping track of multiple instances. Here's an [example](https://github.com/WordPress/gutenberg/pull/34153#issuecomment-908342367).
+
+## Custom Types
+
+```ts
+type DialogInputEvent =
+	| KeyboardEvent< HTMLDivElement >
+	| MouseEvent< HTMLButtonElement >
+```
+
+## Props
+
+### `isOpen`: `boolean`
+
+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.
+
+### `onConfirm`: `( event: DialogInputEvent ) => void`
+
+- Required: Yes
+
+The callback that's called when the user confirms. A confirmation can happen when the `OK` button is clicked or when `Enter` is pressed.
+
+### `onCancel`: `(event: DialogInputEvent ) => void`
+
+- Required: Yes if `isOpen` is set, No if `isOpen` is not set
+
+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.

packages/components/src/confirm-dialog/component.tsx

@@ -0,0 +1,116 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import React, { useEffect, useState } from 'react';
+// eslint-disable-next-line no-restricted-imports
+import type { Ref, MouseEvent, KeyboardEvent } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import Modal from '../modal';
+import type { OwnProps, DialogInputEvent } from './types';
+import {
+	useContextSystem,
+	contextConnect,
+	WordPressComponentProps,
+} from '../ui/context';
+import { Flex } from '../flex';
+import Button from '../button';
+import * as styles from './styles';
+import { useCx } from '../utils/hooks/use-cx';
+
+function ConfirmDialog(
+	props: WordPressComponentProps< OwnProps, 'div', false >,
+	forwardedRef: Ref< any >
+) {
+	const {
+		isOpen: isOpenProp,
+		title,
+		message,
+		onConfirm,
+		onCancel,
+		...otherProps
+	} = useContextSystem( props, 'ConfirmDialog' );
+
+	const hasTitle = !! title;
+	const cx = useCx();
+	const wrapperClassNames = cx(
+		styles.wrapper,
+		! hasTitle && styles.withoutTitle
+	);
+	const buttonsWrapperClassNames = cx( styles.buttonsWrapper );
+
+	const [ isOpen, setIsOpen ] = useState< boolean >();
+	const [ selfClose, setSelfClose ] = useState< boolean >();
+
+	useEffect( () => {
+		// We only allow the dialog to close itself if `isOpenProp` is *not* set.
+		// If `isOpenProp` is set, then it (probably) means it's controlled by a
+		// parent component. In that case, `selfClose` might do more harm than
+		// good, so we disable it.
+		const isIsOpenSet = typeof isOpenProp !== 'undefined';
+		setIsOpen( isIsOpenSet ? isOpenProp : true );
+		setSelfClose( ! isIsOpenSet );
+	}, [ isOpenProp ] );
+
+	const handleEvent = ( callback: ( event: DialogInputEvent ) => void ) => (
+		event: DialogInputEvent
+	) => {
+		// `onCancel` is optional
+		callback?.( event );
+		if ( selfClose ) {
+			setIsOpen( false );
+		}
+	};
+
+	const handleEnter = ( event: KeyboardEvent< HTMLDivElement > ) => {
+		if ( event.key === 'Enter' ) {
+			handleEvent( onConfirm )( event );
+		}
+	};
+
+	return (
+		<>
+			{ isOpen && (
+				<Modal
+					title={ title }
+					overlayClassName={ wrapperClassNames }
+					onRequestClose={ handleEvent( onCancel ) }
+					onKeyDown={ handleEnter }
+					closeButtonLabel={ __( 'Cancel' ) }
+					isDismissible={ true }
+					forwardedRef={ forwardedRef }
+					{ ...otherProps }
+				>
+					<p>{ message }</p>
+					<Flex
+						justify="flex-end"
+						className={ buttonsWrapperClassNames }
+					>
+						<Button
+							variant="tertiary"
+							onClick={ handleEvent( onCancel ) }
+						>
+							{ __( 'Cancel' ) }
+						</Button>
+						<Button
+							variant="primary"
+							onClick={ handleEvent( onConfirm ) }
+						>
+							{ __( 'OK' ) }
+						</Button>
+					</Flex>
+				</Modal>
+			) }
+		</>
+	);
+}
+
+export default contextConnect( ConfirmDialog, 'ConfirmDialog' );

packages/components/src/confirm-dialog/index.tsx

@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies
+ */
+import ConfirmDialog from './component';
+
+export { ConfirmDialog };

packages/components/src/confirm-dialog/stories/index.js

@@ -0,0 +1,126 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import React, { useState } from 'react';
+import { text } from '@storybook/addon-knobs';
+
+/**
+ * Internal dependencies
+ */
+import Button from '../../button';
+import { ConfirmDialog } from '..';
+
+export default {
+	component: ConfirmDialog,
+	title: 'Components (Experimental)/ConfirmDialog',
+};
+
+const daText = () =>
+	text( 'message', 'Would you like to privately publish the post now?' );
+
+// Simplest usage: just declare the component with the required `onConfirm` prop.
+export const _default = () => {
+	const [ confirmVal, setConfirmVal ] = useState( 'Not confirmed' );
+
+	return (
+		<>
+			<ConfirmDialog
+				message={ daText() }
+				onConfirm={ () => setConfirmVal( 'Confirmed!' ) }
+			/>
+			<h1>{ confirmVal }</h1>
+		</>
+	);
+};
+
+export const WithTitle = () => {
+	const [ confirmVal, setConfirmVal ] = useState( 'Not confirmed' );
+
+	return (
+		<>
+			<ConfirmDialog
+				title="Are you sure?"
+				message={ daText() }
+				onConfirm={ () => setConfirmVal( 'Confirmed!' ) }
+			/>
+			<h1>{ confirmVal }</h1>
+		</>
+	);
+};
+
+export const WithJSXMessage = () => {
+	const [ confirmVal, setConfirmVal ] = useState( 'Not confirmed' );
+
+	return (
+		<>
+			<ConfirmDialog
+				message={ <h1>{ daText() }</h1> }
+				onConfirm={ () => setConfirmVal( 'Confirmed!' ) }
+			/>
+			<h1>{ confirmVal }</h1>
+		</>
+	);
+};
+
+export const VeeeryLongMessage = () => {
+	const [ confirmVal, setConfirmVal ] = useState( 'Not confirmed' );
+
+	return (
+		<>
+			<ConfirmDialog
+				message={ daText().repeat( 20 ) }
+				onConfirm={ () => setConfirmVal( 'Confirmed!' ) }
+			/>
+			<h1>{ confirmVal }</h1>
+		</>
+	);
+};
+
+export const UncontrolledAndWithExplicitOnCancel = () => {
+	const [ confirmVal, setConfirmVal ] = useState( 'Not confirmed' );
+
+	return (
+		<>
+			<ConfirmDialog
+				message={ daText() }
+				onConfirm={ () => setConfirmVal( 'Confirmed!' ) }
+				onCancel={ () => setConfirmVal( 'Cancelled' ) }
+			/>
+			<h1>{ confirmVal }</h1>
+		</>
+	);
+};
+
+// Controlled `ConfirmDialog`s require both `onConfirm` *and* `onCancel to be passed
+// It's expected that the user will then use it to hide the dialog, too (see the
+// `setIsOpen` calls below).
+export const Controlled = () => {
+	const [ isOpen, setIsOpen ] = useState( false );
+	const [ confirmVal, setConfirmVal ] = useState( 'Not confirmed' );
+
+	const handleConfirm = () => {
+		setConfirmVal( 'Confirmed!' );
+		setIsOpen( false );
+	};
+
+	const handleCancel = () => {
+		setConfirmVal( 'Cancelled' );
+		setIsOpen( false );
+	};
+
+	return (
+		<>
+			<ConfirmDialog
+				message={ daText() }
+				isOpen={ isOpen }
+				onConfirm={ handleConfirm }
+				onCancel={ handleCancel }
+			/>
+			<Button variant="primary" onClick={ () => setIsOpen( true ) }>
+				Open ConfirmDialog
+			</Button>
+			<h1>{ confirmVal }</h1>
+		</>
+	);
+};

packages/components/src/confirm-dialog/styles.ts

@@ -0,0 +1,27 @@
+/**
+ * External dependencies
+ */
+import { css } from '@emotion/react';
+
+export const wrapper = css`
+	z-index: 9999999;
+`;
+
+// @todo it's unfortunate that I had to hardcode 24px below, given the SCSSs use
+// variables (i.e  https://github.com/WordPress/gutenberg/blob/trunk/packages/components/src/modal/style.scss#L112)
+// Should I perhaps use any of the consts from here? https://github.com/WordPress/gutenberg/blob/trunk/packages/components/src/utils/config-values.js?
+// if you know a better way to adjust this, let me know! -Marcelo
+export const withoutTitle = css`
+	.components-modal__header {
+		display: none;
+	}
+
+	.components-modal__content {
+		margin: 0;
+		padding-top: 24px;
+	}
+`;
+
+export const buttonsWrapper = css`
+	padding-top: 20px;
+`;