expose show()/close() methods via Dialog.useInstance()

.changeset/eight-rocks-dream.md

@@ -0,0 +1,14 @@
+---
+"@itwin/itwinui-react": minor
+---
+
+Added the ability to control `Dialog` imperatively using `show()` and `close()` methods from its instance.
+
+```tsx
+const dialog = Dialog.useInstance();
+
+<Button onClick={() => dialog.show()}>Open dialog</Button>
+<Dialog instance={dialog}>
+  <Button onClick={() => dialog.close()}>Close dialog</Button>
+</Dialog>
+```

apps/react-workshop/src/Dialog.stories.tsx

@@ -9,50 +9,25 @@ export default {
   title: 'Dialog',
 };
 
-export const Basic = () => {
-  const [isOpen, setIsOpen] = React.useState(false);
-
-  const closeDialog = () => {
-    setIsOpen(false);
-  };
-
-  const onClose = () => {
-    console.log('onClose');
-    closeDialog();
-  };
-
-  const primaryButtonHandle = () => {
-    console.log('Primary button');
-    closeDialog();
-  };
+const lorem = `Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.`;
 
-  const secondaryButtonHandle = () => {
-    console.log('Secondary button');
-    closeDialog();
-  };
+export const Basic = () => {
+  const dialog = Dialog.useInstance();
 
   return (
     <>
-      <Button styleType='high-visibility' onClick={() => setIsOpen(true)}>
+      <Button styleType='high-visibility' onClick={() => dialog.show()}>
         Open Dialog
       </Button>
-      <Dialog isOpen={isOpen} onClose={onClose} closeOnEsc isDismissible>
+      <Dialog instance={dialog}>
         <Dialog.Main>
           <Dialog.TitleBar titleText='Best dialog ever' />
-          <Dialog.Content>
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-            eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
-            ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
-            aliquip ex ea commodo consequat. Duis aute irure dolor in
-            reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
-            pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
-            culpa qui officia deserunt mollit anim id est laborum.
-          </Dialog.Content>
+          <Dialog.Content>{lorem}</Dialog.Content>
           <Dialog.ButtonBar>
-            <Button styleType='high-visibility' onClick={primaryButtonHandle}>
+            <Button styleType='high-visibility' onClick={() => dialog.close()}>
               Primary
             </Button>
-            <Button onClick={secondaryButtonHandle}>Secondary</Button>
+            <Button onClick={() => dialog.close()}>Secondary</Button>
           </Dialog.ButtonBar>
         </Dialog.Main>
       </Dialog>
@@ -61,59 +36,29 @@ export const Basic = () => {
 };
 
 export const Modal = () => {
-  const [isOpen, setIsOpen] = React.useState(false);
-
-  const closeDialog = () => {
-    setIsOpen(false);
-  };
-
-  const onClose = () => {
-    console.log('onClose');
-    closeDialog();
-  };
-
-  const primaryButtonHandle = () => {
-    console.log('Primary button');
-    closeDialog();
-  };
-
-  const secondaryButtonHandle = () => {
-    console.log('Secondary button');
-    closeDialog();
-  };
+  const dialog = Dialog.useInstance();
 
   return (
     <>
-      <Button styleType='high-visibility' onClick={() => setIsOpen(true)}>
+      <Button styleType='high-visibility' onClick={() => dialog.show()}>
         Open Dialog
       </Button>
       <Dialog
-        isOpen={isOpen}
-        onClose={onClose}
-        closeOnEsc
+        instance={dialog}
         closeOnExternalClick
         preventDocumentScroll
         trapFocus
         setFocus
-        isDismissible
       >
-        <Dialog.Backdrop onKeyDown={() => console.log('onKeyDown')} />
+        <Dialog.Backdrop />
         <Dialog.Main>
           <Dialog.TitleBar titleText='Best dialog ever' />
-          <Dialog.Content>
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-            eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
-            ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
-            aliquip ex ea commodo consequat. Duis aute irure dolor in
-            reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
-            pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
-            culpa qui officia deserunt mollit anim id est laborum.
-          </Dialog.Content>
+          <Dialog.Content>{lorem}</Dialog.Content>
           <Dialog.ButtonBar>
-            <Button styleType='high-visibility' onClick={primaryButtonHandle}>
+            <Button styleType='high-visibility' onClick={() => dialog.close()}>
               Primary
             </Button>
-            <Button onClick={secondaryButtonHandle}>Secondary</Button>
+            <Button onClick={() => dialog.close()}>Secondary</Button>
           </Dialog.ButtonBar>
         </Dialog.Main>
       </Dialog>
@@ -158,15 +103,7 @@ export const DraggableAndResizable = () => {
       >
         <Dialog.Main>
           <Dialog.TitleBar titleText='Best dialog ever' />
-          <Dialog.Content>
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-            eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
-            ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
-            aliquip ex ea commodo consequat. Duis aute irure dolor in
-            reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
-            pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
-            culpa qui officia deserunt mollit anim id est laborum.
-          </Dialog.Content>
+          <Dialog.Content>{lorem}</Dialog.Content>
           <Dialog.ButtonBar>
             <Button styleType='high-visibility' onClick={primaryButtonHandle}>
               Primary
@@ -230,15 +167,7 @@ export const DraggableRelativeToContainer = () => {
       >
         <Dialog.Main>
           <Dialog.TitleBar titleText='Best dialog ever' />
-          <Dialog.Content>
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-            eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
-            ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
-            aliquip ex ea commodo consequat. Duis aute irure dolor in
-            reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
-            pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
-            culpa qui officia deserunt mollit anim id est laborum.
-          </Dialog.Content>
+          <Dialog.Content>{lorem}</Dialog.Content>
           <Dialog.ButtonBar>
             <Button styleType='high-visibility' onClick={primaryButtonHandle}>
               Primary
@@ -287,15 +216,7 @@ export const Placement = () => {
       >
         <Dialog.Main>
           <Dialog.TitleBar titleText='Best dialog ever' />
-          <Dialog.Content>
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-            eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
-            ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
-            aliquip ex ea commodo consequat. Duis aute irure dolor in
-            reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
-            pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
-            culpa qui officia deserunt mollit anim id est laborum.
-          </Dialog.Content>
+          <Dialog.Content>{lorem}</Dialog.Content>
           <Dialog.ButtonBar>
             <Button styleType='high-visibility' onClick={primaryButtonHandle}>
               Primary

apps/website/src/content/docs/dialog.mdx

@@ -15,7 +15,7 @@ A dialog informs users about a task and can contain critical information, requir
 
 Dialogs are purposefully interruptive, so they should be used sparingly.
 
-## Dialog VS Modal
+## Dialog vs Modal
 
 The terms dialog and modal are often used interchangeably. Within iTwinUI we differentiate the two terms like so:
 
@@ -26,7 +26,31 @@ The terms dialog and modal are often used interchangeably. Within iTwinUI we dif
   <AllExamples.DialogModalExample client:load />
 </LiveExample>
 
-## Variants
+## Usage
+
+The dialog can be opened and closed in two ways:
+
+1. By using the `show()` and `close()` methods from its instance.
+
+   ```tsx
+   const dialog = Dialog.useInstance();
+
+   <Button onClick={() => dialog.show()}>Open dialog</Button>
+   <Dialog instance={dialog}>
+     <Button onClick={() => dialog.close()}>Close dialog</Button>
+   </Dialog>
+   ```
+
+2. By using the `isOpen` prop, often paired with `onClose` and a state variable.
+
+   ```tsx
+   const [isDialogOpen, setIsDialogOpen] = React.useState(false);
+
+   <Button onClick={() => setIsDialogOpen(true)}>Open dialog</Button>
+   <Dialog isOpen={isDialogOpen} onClose={() => setIsDialogOpen(false)}>
+     <Button onClick={() => setIsDialogOpen(false)}>Close dialog</Button>
+   </Dialog>
+   ```
 
 ### Dismissible
 

examples/Dialog.draggable.jsx

@@ -3,7 +3,6 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
-// import * as ReactDOM from 'react-dom';
 import {
   Dialog,
   Button,
@@ -12,38 +11,26 @@ import {
 } from '@itwin/itwinui-react';
 
 export default () => {
-  const [isOpen, setIsOpen] = React.useState(false);
+  const dialog = Dialog.useInstance();
 
   return (
     <>
-      <Button styleType='high-visibility' onClick={() => setIsOpen(true)}>
+      <Button styleType='high-visibility' onClick={() => dialog.show()}>
         Open draggable dialog
       </Button>
 
-      <Dialog
-        isOpen={isOpen}
-        onClose={() => setIsOpen(false)}
-        setFocus={false}
-        closeOnEsc
-        isDismissible
-        isDraggable
-        isResizable
-        portal
-      >
+      <Dialog instance={dialog} isDraggable isResizable portal>
         <Dialog.Main>
           <Dialog.TitleBar titleText='New message' />
           <Dialog.Content>
             <LabeledInput label='Subject' />
             <LabeledTextarea label='Message' />
           </Dialog.Content>
           <Dialog.ButtonBar>
-            <Button
-              styleType='high-visibility'
-              onClick={() => setIsOpen(false)}
-            >
+            <Button styleType='high-visibility' onClick={() => dialog.close()}>
               Submit
             </Button>
-            <Button onClick={() => setIsOpen(false)}>Save draft</Button>
+            <Button onClick={() => dialog.close()}>Save draft</Button>
           </Dialog.ButtonBar>
         </Dialog.Main>
       </Dialog>

examples/Dialog.main.jsx

@@ -3,26 +3,22 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
-// import * as ReactDOM from 'react-dom';
 import { Dialog, Button } from '@itwin/itwinui-react';
 
 export default () => {
-  const [isOpen, setIsOpen] = React.useState(false);
+  const dialog = Dialog.useInstance();
 
   return (
     <>
-      <Button styleType='high-visibility' onClick={() => setIsOpen(true)}>
+      <Button styleType='high-visibility' onClick={() => dialog.show()}>
         Open dialog
       </Button>
       <Dialog
-        isOpen={isOpen}
-        onClose={() => setIsOpen(false)}
-        closeOnEsc
+        instance={dialog}
         closeOnExternalClick
         preventDocumentScroll
         trapFocus
         setFocus
-        isDismissible
         portal
       >
         <Dialog.Backdrop />
@@ -35,13 +31,10 @@ export default () => {
             ask for a decision.
           </Dialog.Content>
           <Dialog.ButtonBar>
-            <Button
-              styleType='high-visibility'
-              onClick={() => setIsOpen(false)}
-            >
+            <Button styleType='high-visibility' onClick={() => dialog.close()}>
               Primary
             </Button>
-            <Button onClick={() => setIsOpen(false)}>Secondary</Button>
+            <Button onClick={() => dialog.close()}>Secondary</Button>
           </Dialog.ButtonBar>
         </Dialog.Main>
       </Dialog>

examples/Dialog.nondismissible.jsx

@@ -3,24 +3,17 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
-// import * as ReactDOM from 'react-dom';
 import { Dialog, Button } from '@itwin/itwinui-react';
 
 export default () => {
-  const [isOpen, setIsOpen] = React.useState(false);
+  const dialog = Dialog.useInstance();
 
   return (
     <>
-      <Button styleType='high-visibility' onClick={() => setIsOpen(true)}>
+      <Button styleType='high-visibility' onClick={() => dialog.show()}>
         Open non-dismissible dialog
       </Button>
-      <Dialog
-        isOpen={isOpen}
-        onClose={() => setIsOpen(false)}
-        setFocus={false}
-        isDismissible={false}
-        portal
-      >
+      <Dialog instance={dialog} setFocus={false} isDismissible={false} portal>
         <Dialog.Backdrop />
         <Dialog.Main>
           <Dialog.TitleBar titleText='Empty trash' />
@@ -29,13 +22,10 @@ export default () => {
             You can't undo this action.
           </Dialog.Content>
           <Dialog.ButtonBar>
-            <Button
-              styleType='high-visibility'
-              onClick={() => setIsOpen(false)}
-            >
+            <Button styleType='high-visibility' onClick={() => dialog.close()}>
               Empty trash
             </Button>
-            <Button onClick={() => setIsOpen(false)}>Cancel</Button>
+            <Button onClick={() => dialog.close()}>Cancel</Button>
           </Dialog.ButtonBar>
         </Dialog.Main>
       </Dialog>