2.4.0 Release (#168)

a16n-dev · web-flow · commit 45ae0913d60c · 2025-08-20T11:01:21.000+10:00
Co-authored-by: Alex Nicholson &lt;alex.n@clove.kitchen&gt;
diff --git a/README.md b/README.md
@@ -39,7 +39,7 @@ const App = () => {
   const questionDialog = useDialog(QuestionDialog);
 
   const handleClick = async () => {
-    const response = await questionDialog.show({
+    const response = await questionDialog.open({
       // pass data to the dialog 
       question: "Do you like apples?" 
     }); 
diff --git a/docs/blog/2025-08-19-deprecating-show-hide.md b/docs/blog/2025-08-19-deprecating-show-hide.md
@@ -0,0 +1,32 @@
+---
+title: Deprecating show/hide in favour of open/close
+description: Notice for a breaking change in the next major release
+tags: [Other]
+---
+
+As of the next major release (3.0.0), the `show()` and `hide()` methods of `useDialog()` will be deprecated in favour of `open()` and `close()`. There is currently no set date for this release, but we wanted to give you a heads up so you can migrate ahead of time
+<!-- truncate -->
+
+## Why?
+The naming of "show" and "hide" imply that the dialog always exists, and is just being shown and hidden. This is misleading, and doesn't accurately reflect how the library works. Dialogs are created and destroyed every time they're opened, ensuring that they have clean state to prevent issues with stale state that arise especially when using forms or other stateful components within dialogs.
+
+## What do I need to do?
+
+Nothing, yet. There is no set date for the next major release, and it will likely be some number of months away. That being said, you can start migrating your code now, as the new methods are already available in the current version of the library and follow the exact same API & implementation as the old methods.
+
+```tsx
+const myDialog = useDialog(MyDialog);
+
+// Replace this
+await myDialog.show(...);
+await myDialog.hide();
+
+// With this
+await myDialog.open(...);
+await myDialog.close();
+```
+
+---
+
+Feedback or ideas? We'd love to hear them! Open an issue over on [GitHub](https://github.com/a16n-dev/react-dialog-async/issues).
+
diff --git a/docs/blog/2025-08-19-release-2-4-0.md b/docs/blog/2025-08-19-release-2-4-0.md
@@ -0,0 +1,17 @@
+---
+title: V2.4.0 has been released
+description: Release notes for version 2.4.0
+tags: [Release, Minor Release]
+---
+
+Version 2.4.0 for React Dialog Async has been released 🎉
+<!-- truncate -->
+
+## What's new?
+* Dialog components are now passed a `focused` prop. This is a boolean indicating if the dialog is "focused" or not. This is useful for handling cases where multiple dialogs are open at the same time.
+* Added deprecation warnings for `show()` and `hide()` methods on `useDialog()`. These methods will be removed in the next major release. [Read more here](/blog/2025/08/19/deprecating-show-hide)
+* Added a deprecation warning for the `mounted` prop passed to dialog components. This prop will be removed in the next major release
+---
+
+Feedback or ideas? We'd love to hear them! Open an issue over on [GitHub](https://github.com/a16n-dev/react-dialog-async/issues).
+
diff --git a/docs/docs/API/use-dialog.md b/docs/docs/API/use-dialog.md
@@ -13,7 +13,7 @@ A hook that takes in a dialog component and then returns methods for interacting
 const exampleDialog = useDialog(ExampleDialog);
 
 const onClick = async () => {
-  await exampleDialog.show();
+  await exampleDialog.open();
 }
 ```
 
@@ -30,7 +30,7 @@ const myDialog = useDialog(MyDialog, {
 
 Available options are:
 
-* `defaultData` - Default data to pass to the dialog component. Specifying this makes passing data to `.show()` optional, but data passed to `.show()` will still override the default data.
+* `defaultData` - Default data to pass to the dialog component. Specifying this makes passing data to `.open()` optional, but data passed to `.show()` will still override the default data.
 * `unmountDelayInMs` - Specify a delay in milliseconds to wait before unmounting the dialog component after it is closed. See the [animations](/animations) section for more information.
 * `customKey` - By default, only one instance of a dialog component is stored internally, regardless of how many places it is used with `useDialog`. If this behaviour is not desired, a `customKey` can be specified to create a new instance of the dialog component.
 * `hideOnHookUnmount` - If set to false, the dialog will not be hidden when the hook is unmounted. This can be useful if you want to open a dialog from a component that is short-lived, like a toast or tooltip.
diff --git a/docs/docs/basics/intro.mdx b/docs/docs/basics/intro.mdx
@@ -51,7 +51,7 @@ function MyComponent() {
   const dialog = useDialog(MyDialog);
 
   return (
-    <button onClick={() => dialog.show()}>
+    <button onClick={() => dialog.open()}>
       Show dialog
     </button>
   );
diff --git a/docs/docs/basics/typescript.md b/docs/docs/basics/typescript.md
@@ -29,7 +29,7 @@ If you use the above dialog, you'll notice the result returned is of type `boole
 
 ```tsx
 // result has type "boolean | undefined"
-const result = await confirmationDialog.show('Are you sure?');
+const result = await confirmationDialog.open('Are you sure?');
 ```
 This is because we can never be sure the dialog is closed with a result, and you should always handle this case in your code.
 
diff --git a/docs/docs/guides/alert-dialog.md b/docs/docs/guides/alert-dialog.md
@@ -43,7 +43,7 @@ export function Page() {
   
   const handleClick = async () => {
     // Data will be passed to props.data in the dialog
-    await alertDialog.show({ 
+    await alertDialog.open({ 
       title: 'Alert', 
       message: 'Hello, world!' 
     });
diff --git a/docs/docs/guides/confirmation-dialog.md b/docs/docs/guides/confirmation-dialog.md
@@ -40,7 +40,7 @@ export function Page() {
   const confirmationDialog = useDialog(ConfirmationDialog);
   
   const handleClick = async () => {
-    const response = await confirmationDialog.show('Are you sure?');
+    const response = await confirmationDialog.open('Are you sure?');
     
     if(response === undefined) {
       console.log('Userclosed the dialog')
diff --git a/docs/docs/guides/first-dialog.md b/docs/docs/guides/first-dialog.md
@@ -37,7 +37,7 @@ export function Page() {
   const simpleDialog = useDialog(SimpleDialog);
   
   const handleClick = async () => {
-    await simpleDialog.show();
+    await simpleDialog.open();
     
     // This code will run after the dialog is closed
     console.log('User closed the dialog');
diff --git a/packages/react-dialog-async/package.json b/packages/react-dialog-async/package.json
@@ -2,7 +2,7 @@
   "name": "react-dialog-async",
   "description": "A promise-based way to show dialogs in React",
   "type": "module",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "sideEffects": false,
   "main": "index.js",
   "module": "index.esm.js",
diff --git a/packages/react-dialog-async/src/DialogProvider/DialogProvider.tsx b/packages/react-dialog-async/src/DialogProvider/DialogProvider.tsx
@@ -113,6 +113,16 @@ const DialogProvider = ({
 
   const dialogComponents = useRenderDialogs(dialogState);
 
+  if (
+    process.env.NODE_ENV !== 'production' &&
+    !usingOutlet &&
+    dialogComponents.length > 0
+  ) {
+    console.warn(
+      'Rendering a dialog without a <DialogOutlet/>. Please include a <DialogOutlet/> as a child of <DialogProvider/> to ensure dialogs are rendered within the correct contexts - this will be required in the next major version of react-dialog-async. See https://react-dialog-async.a16n.dev/API/dialog-outlet for more details. This warning is only present in development',
+    );
+  }
+
   useEffect(() => {
     return () => {
       Object.values(unmountDelayTimeoutRefs.current).forEach(clearTimeout);
diff --git a/packages/react-dialog-async/src/types.ts b/packages/react-dialog-async/src/types.ts
@@ -2,7 +2,11 @@ import type { ComponentType } from 'react';
 
 export interface AsyncDialogProps<Request = void, Response = undefined> {
   open: boolean;
-  mounted: boolean;
+  focused: boolean;
+  /**
+   * @deprecated - This prop will always be set to true. It will be removed in the next major version
+   */
+  mounted: true;
   handleClose: (data?: Response) => void;
   data: Request;
 }
@@ -18,17 +22,13 @@ export type DialogComponent<D, R> = ComponentType<AsyncDialogProps<D, R>>;
 
 export type useDialogReturn<D, R, DE extends D | undefined> = {
   /**
-   * Shows the dialog, and passes the provided data as props to the dialog
-   * component. Returns a promise that resolves when the dialog is closed.
-   *
-   * The resolved value is the value passed to `handleClose` in the dialog
-   * component.
+   * @Deprecated - use `dialog.open()` instead. Read more here: https://react-dialog-async.a16n.dev/blog/2025/08/19/deprecating-show-hide
    */
   show: DE extends undefined
     ? (data: D) => Promise<R | undefined>
     : (data?: D) => Promise<R | undefined>;
   /**
-   * Hides the dialog
+   * @Deprecated - use `dialog.close()` instead. Read more here: https://react-dialog-async.a16n.dev/blog/2025/08/19/deprecating-show-hide
    */
   hide: () => void;
   /**
@@ -37,20 +37,25 @@ export type useDialogReturn<D, R, DE extends D | undefined> = {
    */
   updateData: (data: D) => void;
   /**
-   * Alias for `show`
+   * opens the dialog, and passes the provided data as props to the dialog
+   * component. Returns a promise that resolves when the dialog is closed.
+   *
+   * The promise will resolve to the value that is passed to `handleClose`
+   * within the dialog component.
    */
   open: DE extends undefined
     ? (data: D) => Promise<R | undefined>
-    : () => Promise<R | undefined>;
+    : (data?: D) => Promise<R | undefined>;
   /**
-   * Alias for `hide`
+   * Force closes the dialog. Generally avoid calling this method as it can
+   * lead to poor user experience
    */
   close: () => void;
 };
 
 export type useDialogOptions<D, DE extends D | undefined> = {
   /**
-   * Default data to pass to the dialog when .show() is called
+   * Default data to pass to the dialog when .open() is called
    */
   defaultData?: DE;
   /**
diff --git a/packages/react-dialog-async/src/useDialog.test.tsx b/packages/react-dialog-async/src/useDialog.test.tsx
@@ -33,7 +33,7 @@ test('data is used when default data is not provided', () => {
     const testDialog = useDialog(TestDialogWithData);
 
     useEffect(() => {
-      testDialog.show(message);
+      testDialog.open(message);
     }, []);
 
     return null;
@@ -56,7 +56,7 @@ test('default data is used when data is not provided', () => {
     });
 
     useEffect(() => {
-      testDialog.show();
+      testDialog.open();
     }, []);
 
     return null;
@@ -79,7 +79,7 @@ test('default data is overridden when data is provided', () => {
     });
 
     useEffect(() => {
-      testDialog.show('Hello World!');
+      testDialog.open('Hello World!');
     }, []);
 
     return null;
@@ -109,11 +109,11 @@ test('unmount delay does not delay the promise being resolved', async () => {
   let promise: Promise<void> | undefined;
 
   act(() => {
-    promise = result.result.current.show().then(() => {
+    promise = result.result.current.open().then(() => {
       value = true;
     });
 
-    result.result.current.hide();
+    result.result.current.close();
   });
 
   await promise;
diff --git a/packages/react-dialog-async/src/useRenderDialogs.tsx b/packages/react-dialog-async/src/useRenderDialogs.tsx
@@ -3,19 +3,27 @@ import React, { useMemo } from 'react';
 
 const useRenderDialogs = (state: dialogsStateData) => {
   return useMemo(() => {
-    return Object.entries(state).map(
-      ([id, { dialog: Component, data, open, resolve }]) => {
-        return (
-          <Component
-            key={id}
-            open={open}
-            data={data}
-            mounted={true} // Dialog is always mounted when it's being rendered
-            handleClose={(value) => resolve?.(value)}
-          />
-        );
-      },
-    );
+    const entries = Object.entries(state);
+
+    // Figure out which dialog has focus.
+    // This isn't super efficient, but should be fine given that having more than 2-3 open dialogs would be very unusual
+    let lastOpenDialog: string;
+    entries.forEach(([id, { open }]) => {
+      if (open) lastOpenDialog = id;
+    });
+
+    return entries.map(([id, { dialog: Component, data, open, resolve }]) => {
+      return (
+        <Component
+          key={id}
+          open={open}
+          data={data}
+          mounted={true} // Dialog is always mounted when it's being rendered
+          handleClose={(value) => resolve?.(value)}
+          focused={id === lastOpenDialog} // Focus the last dialog in the list
+        />
+      );
+    });
   }, [state]);
 };
 
