From dbac600078b82e06051cbc2a19585cf4ceca5ae2 Mon Sep 17 00:00:00 2001
From: Cagatay Civici <cagatay.civici@gmail.com>
Date: Thu, 2 Nov 2023 09:28:24 +0300
Subject: [PATCH] Updated DynamicDialog documentation

---
 doc/dynamicdialog/AccessibilityDoc.vue        |  2 +-
 doc/dynamicdialog/CloseDialogDoc.vue          | 29 ++-------
 doc/dynamicdialog/CustomizationDoc.vue        | 49 ++++++---------
 doc/dynamicdialog/DialogServiceDoc.vue        | 30 +++++-----
 doc/dynamicdialog/EmitsDoc.vue                | 50 ----------------
 doc/dynamicdialog/EventsDoc.vue               | 45 ++++++++++++++
 .../{UsageDoc.vue => ExampleDoc.vue}          | 13 ++--
 doc/dynamicdialog/OpenDialogDoc.vue           | 48 +++++++--------
 doc/dynamicdialog/PassingDataDoc.vue          | 60 +++++++++++--------
 doc/dynamicdialog/demo/FooterDemo.vue         |  3 +-
 pages/dynamicdialog/index.vue                 | 26 ++++----
 11 files changed, 160 insertions(+), 195 deletions(-)
 delete mode 100644 doc/dynamicdialog/EmitsDoc.vue
 create mode 100644 doc/dynamicdialog/EventsDoc.vue
 rename doc/dynamicdialog/{UsageDoc.vue => ExampleDoc.vue} (93%)

diff --git a/doc/dynamicdialog/AccessibilityDoc.vue b/doc/dynamicdialog/AccessibilityDoc.vue
index c2729cf2d..9d89f057b 100644
--- a/doc/dynamicdialog/AccessibilityDoc.vue
+++ b/doc/dynamicdialog/AccessibilityDoc.vue
@@ -1,5 +1,5 @@
 <template>
     <DocSectionText id="accessibility" label="Accessibility" v-bind="$attrs">
-        <p>DynamicDialog uses the Dialog component internally, visit <NuxtLink to="/dialog/#accessibility">dialog</NuxtLink> for more information.</p>
+        <p>Visit accessibility section of <NuxtLink to="/dialog/#accessibility">dialog</NuxtLink> component for more information.</p>
     </DocSectionText>
 </template>
diff --git a/doc/dynamicdialog/CloseDialogDoc.vue b/doc/dynamicdialog/CloseDialogDoc.vue
index da3dabc30..c4908a75f 100644
--- a/doc/dynamicdialog/CloseDialogDoc.vue
+++ b/doc/dynamicdialog/CloseDialogDoc.vue
@@ -1,8 +1,8 @@
 <template>
     <DocSectionText v-bind="$attrs">
-        <p>The <i>close</i> function of the <i>dialogRef</i> is used to hide a Dialog. The <i>dialogRef</i> is injected to the component that is loaded by the dialog.</p>
+        <p>The <i>close</i> function is available through a <i>dialogRef</i> that is injected to the component loaded by the dialog.</p>
     </DocSectionText>
-    <DocSectionCode :code="code" importCode hideCodeSandbox hideStackBlitz />
+    <DocSectionCode :code="code" importCode hideToggleCode hideCodeSandbox hideStackBlitz />
 </template>
 
 <script>
@@ -11,33 +11,14 @@ export default {
         return {
             code: {
                 basic: `
-export default {
-    inject: ['dialogRef'],
-    methods:{
-        closeDialog() {
-            this.dialogRef.close();
-        }
-    }
-}
-
-`,
-                options: `
-export default {
-    inject: ['dialogRef'],
-    methods:{
-        closeDialog() {
-            this.dialogRef.close();
-        }
-    }
-}
-`,
-                composition: `
 import { inject } from "vue";
 
 const dialogRef = inject('dialogRef');
+
 const closeDialog = () => {
     dialogRef.value.close();
-}`
+}
+`
             }
         };
     }
diff --git a/doc/dynamicdialog/CustomizationDoc.vue b/doc/dynamicdialog/CustomizationDoc.vue
index dd65751a6..420aa3af7 100644
--- a/doc/dynamicdialog/CustomizationDoc.vue
+++ b/doc/dynamicdialog/CustomizationDoc.vue
@@ -1,6 +1,6 @@
 <template>
     <DocSectionText v-bind="$attrs">
-        <p>DynamicDialog uses the Dialog component internally, visit <NuxtLink to="/dialog">dialog</NuxtLink> for more information.</p>
+        <p>DynamicDialog uses the Dialog component internally, visit <NuxtLink to="/dialog">dialog</NuxtLink> for more information about the available props.</p>
     </DocSectionText>
     <DocSectionCode :code="code" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
 </template>
@@ -11,38 +11,27 @@ export default {
         return {
             code: {
                 basic: `
-import { markRaw } from 'vue';
 import ProductListDemo from './ProductListDemo';
-import FooterDemo from './FooterDemo';
+import { useDialog } from 'primevue/usedialog';
 
-export default {
-    methods:{
-        showProducts() {
-            const dialogRef = this.$dialog.open(ProductListDemo, {
-                props: {
-                    header: 'Product List',
-                    style: {
-                        width: '50vw',
-                    },
-                    breakpoints:{
-                        '960px': '75vw',
-                        '640px': '90vw'
-                    },
-                    modal: true
-                },
-                templates: {
-                    footer: markRaw(FooterDemo)
-                },
-                onClose: (options) => {
-                    const data = options.data;
-                    if (data) {
-                        this.$toast.add({ severity:'info', summary: 'Info Message', detail:'Order submitted', life: 3000 });
-                    }
-                }
-            });
+const dialog = useDialog();
+
+const showProducts = () => {
+    dialog.open(ProductListDemo, {
+        props: {
+            header: 'Product List',
+            style: {
+                width: '50vw',
+            },
+            breakpoints:{
+                '960px': '75vw',
+                '640px': '90vw'
+            },
+            modal: true
         }
-    }
-}`
+    });
+}
+`
             }
         };
     }
diff --git a/doc/dynamicdialog/DialogServiceDoc.vue b/doc/dynamicdialog/DialogServiceDoc.vue
index 808d2f0cd..503254006 100644
--- a/doc/dynamicdialog/DialogServiceDoc.vue
+++ b/doc/dynamicdialog/DialogServiceDoc.vue
@@ -1,12 +1,12 @@
 <template>
     <DocSectionText v-bind="$attrs">
-        <p>Dynamic dialogs are controlled via the <i>DialogService</i> that needs to be installed as an application plugin.</p>
+        <p>A single shared dialog instance is required in the application, ideal location would be defining it once at the main application template.</p>
+        <DocSectionCode :code="code1" hideToggleCode hideCodeSandbox hideStackBlitz />
+        <p>A dynamic dialog is controlled via the <i>DialogService</i> that needs to be installed as an application plugin.</p>
+        <DocSectionCode :code="code2" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
+        <p>The service is available with the <i>useDialog</i> function for Composition API or using the <i>$dialog</i> property of the application for Options API.</p>
+        <DocSectionCode :code="code3" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
     </DocSectionText>
-    <DocSectionCode :code="code1" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
-    <div class="doc-section-description">
-        <p><i>$dialog</i> is available as a property in the application instance for Options API. The service can be injected with the <i>useDialog</i> function for Composition API.</p>
-    </div>
-    <DocSectionCode :code="code2" importCode hideCodeSandbox hideStackBlitz />
 </template>
 
 <script>
@@ -15,6 +15,11 @@ export default {
         return {
             code1: {
                 basic: `
+<DynamicDialog />
+`
+            },
+            code2: {
+                basic: `
 import {createApp} from 'vue';
 import DialogService from 'primevue/dialogservice';
 
@@ -22,19 +27,16 @@ const app = createApp(App);
 app.use(DialogService);
 `
             },
-            code2: {
+            code3: {
                 basic: `
+/* Composition API */
 import { useDialog } from 'primevue/usedialog';
 
 const dialog = useDialog();
 
-`,
-                options: `const dialogRef = this.$dialog;
-`,
-                composition: `
-import { useDialog } from 'primevue/usedialog';
-
-const dialog = useDialog();`
+/* Options API */
+const dialog = this.$dialog;
+`
             }
         };
     }
diff --git a/doc/dynamicdialog/EmitsDoc.vue b/doc/dynamicdialog/EmitsDoc.vue
deleted file mode 100644
index fe212173d..000000000
--- a/doc/dynamicdialog/EmitsDoc.vue
+++ /dev/null
@@ -1,50 +0,0 @@
-<template>
-    <DocSectionText v-bind="$attrs">
-        <p>
-            The <i>emits</i> object can be used to handle events emitted by the child component. Each method name used in this object must begin with 'on'. Then the emit name should come. This is an
-            <a href="https://vuejs.org/guide/essentials/event-handling.html#listening-to-events">event handling</a> rule of Vue.
-        </p>
-
-        <DocSectionCode :code="code1" importCode hideToggleCode hideCodeSandbox hideStackBlitz />
-        <DocSectionCode :code="code2" importCode hideToggleCode hideCodeSandbox hideStackBlitz />
-    </DocSectionText>
-</template>
-
-<script>
-export default {
-    data() {
-        return {
-            code1: {
-                basic: `
-this.$dialog.open(ProductListDemo, {
-    emits: {
-        onInfo: (e) => {     // The 'on' prefix and same emit name are required.
-            console.log(e);  // {user: 'primetime'}
-        }
-    },
-};
-`
-            },
-            code2: {
-                basic: `
-// ProductListDemo
-<template>
-    <Button label="Submit" @click="showInfo" />
-</template>
-
-<script>
-export default {
-    emits: ['info'],
-    methods: {
-        showInfo() {
-            this.$emit('info', { user: 'primetime' });
-        }
-    }
-};
-<\/script>
-`
-            }
-        };
-    }
-};
-</script>
diff --git a/doc/dynamicdialog/EventsDoc.vue b/doc/dynamicdialog/EventsDoc.vue
new file mode 100644
index 000000000..043d4ccee
--- /dev/null
+++ b/doc/dynamicdialog/EventsDoc.vue
@@ -0,0 +1,45 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p>The <i>emits</i> object defines callbacks to handle events emitted by the component within the Dialog.</p>
+
+        <DocSectionCode :code="code1" importCode hideToggleCode hideCodeSandbox hideStackBlitz />
+        <DocSectionCode :code="code2" importCode hideToggleCode hideCodeSandbox hideStackBlitz />
+    </DocSectionText>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            code1: {
+                basic: `
+import ProductListDemo from './ProductListDemo';
+import { useDialog } from 'primevue/usedialog';
+
+const dialog = useDialog();
+
+const showProducts = () => {
+    dialog.open(ProductListDemo, {
+        onCancel: (e) => {
+            console.log(e);  // {user: 'primetime'}
+        }
+    });
+}
+`
+            },
+            code2: {
+                basic: `
+<script setup>
+/* ProductListDemo.vue */
+const emit = defineEmits(['onCancel', 'onSave'])
+
+function buttonClick() {
+  emit('onCancel', {user: 'primetime'});
+}
+<\/script>
+`
+            }
+        };
+    }
+};
+</script>
diff --git a/doc/dynamicdialog/UsageDoc.vue b/doc/dynamicdialog/ExampleDoc.vue
similarity index 93%
rename from doc/dynamicdialog/UsageDoc.vue
rename to doc/dynamicdialog/ExampleDoc.vue
index a5da5487d..98e5dd522 100644
--- a/doc/dynamicdialog/UsageDoc.vue
+++ b/doc/dynamicdialog/ExampleDoc.vue
@@ -1,9 +1,6 @@
 <template>
     <DocSectionText v-bind="$attrs">
-        <p>
-            Dialogs can be created dynamically with any component as the content using a DialogService along with a <i>DynamicDialog</i> component. Ideal location of a DynamicDialog is the main template so that it can be used by any component within
-            the application.
-        </p>
+        <p>A sample implementation to demonstrate loading components asynchronously, nested content and passing data.</p>
     </DocSectionText>
     <div class="card flex justify-content-center">
         <Button label="Select a Product" icon="pi pi-search" @click="showProducts" />
@@ -15,7 +12,7 @@
 
 <script>
 import { markRaw } from 'vue';
-import FooterDemo from './demo/FooterDemo.vue';
+import FooterDemo from './demo/FooterDemo';
 import ProductListDemo from './demo/ProductListDemo';
 
 export default {
@@ -239,8 +236,7 @@ export default {
                     'src/components/FooterDemo.vue': {
                         content: `
 <template>
-    <Button type="button" label="No" icon="pi pi-times" @click="closeDialog({ buttonType: 'No' })" text></Button>
-    <Button type="button" label="Yes" icon="pi pi-check" @click="closeDialog({ buttonType: 'Yes' })" autofocus></Button>
+    <Button type="button" label="Cancel" icon="pi pi-times" @click="closeDialog({ buttonType: 'Cancel' })" autofocus></Button>
 </template>
 
 <script>
@@ -349,8 +345,7 @@ const closeDialog = () => {
                     'src/components/FooterDemo.vue': {
                         content: `
 <template>
-    <Button type="button" label="No" icon="pi pi-times" @click="closeDialog({ buttonType: 'No' })" text></Button>
-    <Button type="button" label="Yes" icon="pi pi-check" @click="closeDialog({ buttonType: 'Yes' })" autofocus></Button>
+    <Button type="button" label="Cancel" icon="pi pi-times" @click="closeDialog({ buttonType: 'Cancel' })" autofocus></Button>
 </template>
 
 <script setup>
diff --git a/doc/dynamicdialog/OpenDialogDoc.vue b/doc/dynamicdialog/OpenDialogDoc.vue
index 3b852007b..882da2f51 100644
--- a/doc/dynamicdialog/OpenDialogDoc.vue
+++ b/doc/dynamicdialog/OpenDialogDoc.vue
@@ -1,46 +1,40 @@
 <template>
     <DocSectionText v-bind="$attrs">
         <p>The <i>open</i> function of the <i>DialogService</i> is used to open a Dialog. First parameter is the component to load and second one is the configuration object to customize the Dialog.</p>
+        <DocSectionCode :code="code1" importCode hideToggleCode hideCodeSandbox hideStackBlitz />
+        <p>The component can also be loaded asynchronously, this approach is useful in conditional cases and to improve initial load times as well.</p>
+        <DocSectionCode :code="code2" importCode hideToggleCode hideCodeSandbox hideStackBlitz />
     </DocSectionText>
-    <DocSectionCode :code="code" importCode hideCodeSandbox hideStackBlitz />
 </template>
 
 <script>
 export default {
     data() {
         return {
-            code: {
+            code1: {
                 basic: `
 import ProductListDemo from './ProductListDemo';
-
-export default {
-    methods:{
-        showProducts() {
-            this.$dialog.open(ProductListDemo, {});
-        }
-    }
-}
-
-`,
-                options: `
-import ProductListDemo from './ProductListDemo';
-
-export default {
-    methods:{
-        showProducts() {
-            this.$dialog.open(ProductListDemo, {});
-        }
-    }
-}
-`,
-                composition: `
-import ProductListDemo from './ProductListDemo';
 import { useDialog } from 'primevue/usedialog';
 
+const dialog = useDialog();
+
 const showProducts = () => {
-    const dialog = useDialog();
     dialog.open(ProductListDemo, {});
-}`
+}
+`
+            },
+            code2: {
+                basic: `
+import { useDialog } from 'primevue/usedialog';
+
+const dialog = useDialog();
+
+const dynamicComponent = defineAsyncComponent(() => import('./ProductListDemo.vue'));
+
+const showProducts = () => {
+    dialog.open(dynamicComponent, {});
+}
+`
             }
         };
     }
diff --git a/doc/dynamicdialog/PassingDataDoc.vue b/doc/dynamicdialog/PassingDataDoc.vue
index f4fd8ac85..048eb32d1 100644
--- a/doc/dynamicdialog/PassingDataDoc.vue
+++ b/doc/dynamicdialog/PassingDataDoc.vue
@@ -1,11 +1,11 @@
 <template>
     <DocSectionText v-bind="$attrs">
-        <p>Data can be passed to the component that is loaded by the Dialog and also from the component back to the caller component. Use the <i>open</i> function and pass your parameters with the <i>data</i> property in the options object.</p>
+        <p>Use the <i>data</i> property to pass parameters when opening a Dialog, the internal component can later access this data using <i>dialogRef</i>.</p>
 
         <DocSectionCode :code="code1" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
         <DocSectionCode :code="code2" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
 
-        <p>Similarly when hiding a Dialog, any parameter passed to the <i>close</i> function is received from the <i>onClose</i> callback defined by the <i>open</i> function at the caller.</p>
+        <p>Similarly when hiding a Dialog, any parameter passed to the <i>close</i> function is received from the <i>onClose</i> callback.</p>
         <DocSectionCode :code="code3" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
         <DocSectionCode :code="code4" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
     </DocSectionText>
@@ -17,41 +17,51 @@ export default {
         return {
             code1: {
                 basic: `
-this.$dialog.open(ProductListDemo, {
-    data: {
-        user: 'primetime'
-    }
-};
+const dialog = useDialog();
+
+const showProducts = () => {
+    dialog.open(ProductListDemo, {
+        data: {
+            user: 'primetime'
+        }
+    });
+}
 `
             },
             code2: {
                 basic: `
-export default {
-    inject: ['dialogRef'],
-    mounted:{
-        const params = this.dialogRef.data; // {user: 'primetime'}
-    }
-}
+import { inject, onMounted } from "vue";
+
+const dialogRef = inject('dialogRef');
+
+onMounted(() => {
+    const params = this.dialogRef.data; // {user: 'primetime'}
+})
 `
             },
             code3: {
                 basic: `
-this.$dialog.open(ProductListDemo, {
-    onClose(options) {
-        const callbackParams = options.data; // {id: 12}
-    }
-);
+const dialog = useDialog();
+
+const showProducts = () => {
+    dialog.open(ProductListDemo, {
+        onClose: (opt) => {
+            const callbackParams = opt.data; // {selectedId: 12}
+        }
+    });
+}
 `
             },
             code4: {
                 basic: `
-export default {
-    inject: ['dialogRef'],
-    methods:{
-        closeDialog() {
-            this.dialogRef.close({id: 12});
-        }
-    }
+import { inject } from "vue";
+
+const dialogRef = inject('dialogRef');
+
+const closeDialog = () => {
+    dialogRef.value.close({
+        selectedId: 12
+    });
 }
 `
             }
diff --git a/doc/dynamicdialog/demo/FooterDemo.vue b/doc/dynamicdialog/demo/FooterDemo.vue
index 3605dd9e7..ed59847f2 100644
--- a/doc/dynamicdialog/demo/FooterDemo.vue
+++ b/doc/dynamicdialog/demo/FooterDemo.vue
@@ -1,6 +1,5 @@
 <template>
-    <Button type="button" label="No" icon="pi pi-times" @click="closeDialog({ buttonType: 'No' })" text></Button>
-    <Button type="button" label="Yes" icon="pi pi-check" @click="closeDialog({ buttonType: 'Yes' })" autofocus></Button>
+    <Button type="button" label="Cancel" icon="pi pi-times" @click="closeDialog({ buttonType: 'Cancel' })" autofocus></Button>
 </template>
 
 <script>
diff --git a/pages/dynamicdialog/index.vue b/pages/dynamicdialog/index.vue
index 87fd5e793..be8711624 100644
--- a/pages/dynamicdialog/index.vue
+++ b/pages/dynamicdialog/index.vue
@@ -15,11 +15,11 @@ import AccessibilityDoc from '@/doc/dynamicdialog/AccessibilityDoc.vue';
 import CloseDialogDoc from '@/doc/dynamicdialog/CloseDialogDoc.vue';
 import CustomizationDoc from '@/doc/dynamicdialog/CustomizationDoc.vue';
 import DialogServiceDoc from '@/doc/dynamicdialog/DialogServiceDoc.vue';
-import EmitsDoc from '@/doc/dynamicdialog/EmitsDoc.vue';
+import EventsDoc from '@/doc/dynamicdialog/EventsDoc.vue';
+import ExampleDoc from '@/doc/dynamicdialog/ExampleDoc.vue';
 import ImportDoc from '@/doc/dynamicdialog/ImportDoc.vue';
 import OpenDialogDoc from '@/doc/dynamicdialog/OpenDialogDoc.vue';
 import PassingDataDoc from '@/doc/dynamicdialog/PassingDataDoc.vue';
-import UsageDoc from '@/doc/dynamicdialog/UsageDoc.vue';
 import PTComponent from '@/doc/dynamicdialog/pt/index.vue';
 import ThemingDoc from '@/doc/dynamicdialog/theming/index.vue';
 
@@ -37,16 +37,16 @@ export default {
                     label: 'Dialog Service',
                     component: DialogServiceDoc
                 },
-                {
-                    id: 'usage',
-                    label: 'Usage',
-                    component: UsageDoc
-                },
                 {
                     id: 'open',
                     label: 'Open',
                     component: OpenDialogDoc
                 },
+                {
+                    id: 'customization',
+                    label: 'Customization',
+                    component: CustomizationDoc
+                },
                 {
                     id: 'close',
                     label: 'Close',
@@ -58,14 +58,14 @@ export default {
                     component: PassingDataDoc
                 },
                 {
-                    id: 'emits',
-                    label: 'Emits',
-                    component: EmitsDoc
+                    id: 'events',
+                    label: 'Events',
+                    component: EventsDoc
                 },
                 {
-                    id: 'customization',
-                    label: 'Customization',
-                    component: CustomizationDoc
+                    id: 'example',
+                    label: 'Example',
+                    component: ExampleDoc
                 },
                 {
                     id: 'accessibility',