[RFC] Application Dialogs

[Janpot]

Which problem do we want to solve?

• Dialog interactions is often required to be imperative. e.g. in an async flow, ask the user for confirmation and then proceed with the flow. Many flows involve opening a dialog, passing a payload, waiting for interaction to end and get a result back.
• System dialogs (confirm, alert, prompt) are synchronous APIs, and aren’t MUI theme aware
• Dialogs that are defined in the markup of a component that unmounts when the dialog closes don’t play their closing animation.

How do we want to solve it

• useDialog hook that returns methods for MUI versions of the system dialog and a open function to call a custom dialog imperatively. Example usage:

  import { useDialog } from '@toolpad/core';
  
  // ...
  
  function MyComponent() {
    const dialog = useDialog();
  
    const onClick = async () => {
      try {
        const ok = await dialog.confirm('do you want to delete it?');
        if (ok) {
          await api.deleteItem();
        }
      } catch {
        dialog.alert('oh oh, something went wrong');
      }
    };
  
    return; //...
  }

API

interface AlertOptions {
  title?: React.ReactNode;
  okText?: React.ReactNode;
}

interface ConfirmOptions {
  title?: React.ReactNode;
  color?: 'error' | 'info' | 'success' | 'warning';
  defaultValue?: string;
  okText?: React.ReactNode;
  cancelText?: React.ReactNode;
}

interface PromptOptions {
  title?: React.ReactNode;
  okText?: React.ReactNode;
  cancelText?: React.ReactNode;
}

interface DialogProps<P, R> {
  payload: P;
  open: boolean;
  onClose: (result: R) => void;
}

interface DialogHook {
  alert(msg: React.ReactNode, options: AlertOptions): Promise<void>;
  confirm(msg: React.ReactNode, options: ConfirmOptions): Promise<boolean>;
  prompt(msg: React.ReactNode, options: PromptOptions): Promise<string>;
  open<P, R>(
    Component: React.ComponentType<DialogProps<P, R>>,
    payload: P,
  ): Promise<R>;
  close<R>(dialog: Promise<R>, result: R): Promise<R>;
}

function useDialog(): DialogHook;

Customization

Write your own dialogs that can be used in the imperative API as well as with your own dialog state management solution. Custom dialog components take open and onClose props and a payload. They return a result in the onClose handler.

function NameSayerDialog({
  payload,
  open,
  onClose,
}: DialogProps<string, string | undefined>) {
  return (
    <Dialog open={open} onClose={onClose}>
      <DialogTitle>Hello sayer</DialogTitle>
      <DialogContent>
        <DialogContentText>
          Click Ok to say hello to {payload.name}
        </DialogContentText>
      </DialogContent>
      <DialogActions>
        <Button onClick={() => onclose(`Hello ${payload.name}`)}>Ok</Button>
        <Button onClick={onClose}>Cancel</Button>
      </DialogActions>
    </Dialog>
  );
}

This custom dialog can now be used with the dialog.open() method. Pass it a payload and get a Promise back for the result that was passed to onClose .

const dialog = useDialog();
const msg = await dialog.open(NameSayerDialog, { name: 'John' });
if (typeof msg === 'string') {
  await dialog.alert(msg);
}

The Dialog stack

The dialogs should behave like a stack. Meaning:

• A call to open a new dialog while one is already open should open a new instance on the top.
• Multiple instances of the same dialog can be open at the same time.
• The stack is managed by a DialogProvider component.
• DialogProvider created dialogs render before user content. Dialogs rendered by user content render on top of any dialog managed by DialogProvider .
• The stack will guarantee the order in the DOM of dialogs from older to newer, the user will be responsible for the css z-order. Make sure all dialogs you create have the same z-order. We encourage using the MUI Dialog exclusively.

Closing a dialog programmatically

The close method allows for programmatically closing a dialog and resolving its promise. It takes the promise returned from an open call and closes the dialog associated with it. The function will error if a promise is passed that is not returned from an open call. If the dialog has already been closed, the function is a no-op. Since closing the dialog results in the promise to be resolved, one needs to pass a valid dialog result.

[Janpot]

Did an initial exploratory implementation for crud pages and I think we can make some amendment to the RFC:

A common use-case for something like the confirm dialog is to guard a destructive operation with an explicit confirmation. In many cases this operation is async. Ideally we'd show feedback to the user of the operation in progress. a common sense UX would be to turn the "Ok" button into a loading state at that point, until the operation finishes and the dialog can be closed. We could expand the API to include an asynchronous onClose handler. This would allow for a loading state of the dialog actions between clicking and closing the dialog.

const dialogs = useDialogs()

const handleDeleteClick = React.useCallback(async () =>{
  try {
    await dialogs.confirm(`Do you want to delete ${item}?`, {
      async onClose(confirmed) {
	if (confirmed) {
	  await myDb.delete(item)
	}
      }
    })
  } catch (err) {
    await dialog.alert(`Failed to delete: ${err.message}`);
  }
}, [item, dialogs])

The onClose handler should also run when the user calls dialogs.close(theDialog, true). In essence the dialogs.close method takes the same function as clicking one of the dialog actions.