Merge pull request #490 from devforth/feature/AdminForth/1296/add-docs-for-the-afcl-modal-an

Feature/admin forth/1296/add docs for the afcl modal an

Author: yaroslav8765

adminforth/documentation/docs/tutorial/03-Customization/15-afcl.md

@@ -2317,6 +2317,44 @@ import { JsonViewer } from '@/afcl'
   </div>
 </div>
 
+## Modal
+
+<div class="split-screen" >
+  <div>
+
+```ts
+import { Modal, Button } from '@/afcl';
+```
+
+```html
+  <Modal class="w-96" :closeByClickOutside="true" :closeByEsc="true" askForCloseConfirmation >
+    <template #trigger>
+      <Button>Modal Toggle</Button>
+    </template>
+
+    <div class="space-y-4 p-4">
+      <p>This is the first paragraph of modal content.</p>
+      <p>And this is the second paragraph.</p>
+    </div>
+  </Modal>
+```
+  </div>
+  <div>
+  ![AFCL Dialog](image-98.png)
+  </div>
+</div>
+
+### Props: 
+```ts
+  closeByClickOutside?: boolean  // Close on click outside of modal (default is true)
+  closeByEsc?: boolean // Close on Esc button click (default is true)
+  beforeCloseFunction?: (() => void | Promise<void>) | null // Callback, that will be executed before open
+  beforeOpenFunction?: (() => void | Promise<void>) | null // Callback, that will be executed before close
+  askForCloseConfirmation?: boolean // Show extra popup to confirm close ( to avoid close by accident)
+  closeConfirmationText?: string // Text that will be shown on close confirmation popup
+  removeFromDomOnClose?: boolean // Remove modal from DOM on close ( default is false )
+```
+
 ## Date picker
 
 ```ts

adminforth/documentation/docs/tutorial/03-Customization/image-98.png

@@ -1,124 +1,188 @@
 <template>
-  <div
-    v-if="$slots.trigger"
-    @click="modal?.show()" class="inline-flex items-center cursor-pointer"
+  <Modal 
+    ref="modalRef" 
+    v-bind="$attrs"
+    :closeByClickOutside="clickToCloseOutside || closeByClickOutside"
+    :closeByEsc="closeByEsc || closable"
+    :beforeCloseFunction="beforeCloseFunction"
+    :beforeOpenFunction="beforeOpenFunction"
+    :askForCloseConfirmation="askForCloseConfirmation"
+    :closeConfirmationText="closeConfirmationText"
+    :removeFromDomOnClose="removeFromDomOnClose"
   >
-    <slot name="trigger"></slot>
-  </div>
-  <Teleport to="body">
-    <div ref="modalEl" tabindex="-1" aria-hidden="true" class="[scrollbar-gutter:stable] hidden overflow-y-auto overflow-x-hidden fixed top-0 right-0 left-0 z-50 justify-center items-center w-full md:inset-0 h-full max-h-full">
-      <div v-bind="$attrs" class="relative p-4 max-w-2xl max-h-full" :class="($attrs.class as string)?.includes('w-') ? '' : 'w-full'">
-        <!-- Modal content -->
-        <div class="relative bg-lightDialogBackgorund rounded-lg shadow-sm dark:bg-darkDialogBackgorund">
-          <!-- Modal header -->
-          <div
-            v-if="header"
-            class="flex items-center justify-between p-4 md:p-5 border-b rounded-t dark:border-darkDialogBreakLine border-lightDialogBreakLine"
-          >
-            <h3 class="text-xl font-semibold text-lightDialogHeaderText dark:text-darkDialogHeaderText">
-              {{ header }}
-            </h3>
-            <button
-              v-if="headerCloseButton"
-              type="button"
-              class="text-lightDialogCloseButton bg-transparent hover:bg-lightDialogCloseButtonHoverBackground hover:text-lightDialogCloseButtonHover rounded-lg text-sm w-8 h-8 ms-auto inline-flex justify-center items-center dark:text-darkDialogCloseButton dark:hover:bg-darkDialogCloseButtonHoverBackground dark:hover:text-darkDialogCloseButtonHover"
-              @click="tryToHideModal"
-            >
-              <svg class="w-3 h-3" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 14 14">
-                <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="m1 1 6 6m0 0 6 6M7 7l6-6M7 7l-6 6"/>
-              </svg>
-              <span class="sr-only">Close modal</span>
-            </button>
-          </div>
-          <!-- Modal body -->
-          <div class="p-4 md:p-5 space-y-4 text-lightDialogBodyText dark:text-darkDialogBodyText">
-            <slot></slot>
-          </div>
-          <!-- Modal footer -->
-          <div
-            v-if="buttons.length"
-            class="flex items-center p-4 md:p-5 border-t border-lightDialogBreakLine rounded-b dark:border-darkDialogBreakLine"
-          >
-            <Button
-              v-for="(button, buttonIndex) in buttons"
-              :key="buttonIndex"
-              v-bind="button.options"
-              :class="{ 'ms-3': buttonIndex > 0 }"
-              @click="button.onclick(modal)"
-            >
-              {{ button.label }}
-            </Button>
-          </div>
-        </div>
-      </div>
-      <div>
-        <!-- Confirmation Modal -->
-        <div
-          v-if="showConfirmationOnClose"
-          class="fixed inset-0 flex items-center justify-center bg-black bg-opacity-50 z-[60]"
-        >
-          <div class="bg-white dark:bg-gray-800 p-6 rounded-lg shadow-lg max-w-sm w-full">
-            <h2 class="text-lg font-semibold mb-4 text-lightDialogHeaderText dark:text-darkDialogHeaderText">Confirm Close</h2>
-            <p class="mb-6 text-lightDialogBodyText dark:text-darkDialogBodyText">{{ props.closeConfirmationText }}</p>
-            <div class="flex justify-end">
-              <Button
-                class="me-3 !bg-gray-50 dark:!bg-gray-700 !text-lightDialogBodyText dark:!text-darkDialogBodyText hover:!bg-gray-100 dark:hover:!bg-gray-600 !border-gray-200 dark:!border-gray-600"
-                @click="showConfirmationOnClose = false"
-              >
-                Cancel
-              </Button>
-              <Button
-                @click="
-                  showConfirmationOnClose = false;
-                  modal?.hide();
-                "
-              >
-                Confirm
-              </Button>
-            </div>
-          </div>
-        </div>
-      </div>
+    <template v-if="$slots.trigger" #trigger>
+      <slot name="trigger"></slot>
+    </template>
+
+    <!-- Modal header -->
+    <div
+      v-if="header"
+      class="flex items-center justify-between p-4 md:p-5 border-b rounded-t dark:border-darkDialogBreakLine border-lightDialogBreakLine"
+    >
+      <h3 class="text-xl font-semibold text-lightDialogHeaderText dark:text-darkDialogHeaderText">
+        {{ header }}
+      </h3>
+      <button
+        v-if="headerCloseButton"
+        type="button"
+        class="text-lightDialogCloseButton bg-transparent hover:bg-lightDialogCloseButtonHoverBackground hover:text-lightDialogCloseButtonHover rounded-lg text-sm w-8 h-8 ms-auto inline-flex justify-center items-center dark:text-darkDialogCloseButton dark:hover:bg-darkDialogCloseButtonHoverBackground dark:hover:text-darkDialogCloseButtonHover"
+        @click="tryToHideModal"
+      >
+        <svg class="w-3 h-3" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 14 14">
+          <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="m1 1 6 6m0 0 6 6M7 7l6-6M7 7l-6 6"/>
+        </svg>
+        <span class="sr-only">{{ t('Close Modal') }}</span>
+      </button>
+    </div>
+    <!-- Modal body -->
+    <div class="p-4 md:p-5 text-lightDialogBodyText dark:text-darkDialogBodyText">
+      <slot></slot>
+    </div>
+    <!-- Modal footer -->
+    <div
+      v-if="buttons.length"
+      class="flex items-center p-4 md:p-5 border-t border-lightDialogBreakLine rounded-b dark:border-darkDialogBreakLine"
+    >
+      <Button
+        v-for="(button, buttonIndex) in buttons"
+        :key="buttonIndex"
+        v-bind="button.options"
+        :class="{ 'ms-3': buttonIndex > 0 }"
+        @click="button.onclick(dialog)"
+      >
+        {{ button.label }}
+      </Button>
     </div>
-  </Teleport>
+  </Modal>
 </template>
 
 <script setup lang="ts">
 import Button from "./Button.vue";
-import { ref, onMounted, nextTick, onUnmounted, computed, type Ref } from 'vue';
-import { Modal } from 'flowbite';
+import { ref, computed, type Ref } from 'vue';
+import { Modal } from '@/afcl'
+import { useI18n } from "vue-i18n";
+
+const { t } = useI18n();
+
+
+interface IDialogInsideButtonClickHandler {
+  hide: () => void
+}
 
-const modalEl = ref(null);
-const modal: Ref<Modal|null> = ref(null);
 
 interface DialogButton {
   label: string
-  onclick: (dialog: any) => void
+  onclick: (dialog: IDialogInsideButtonClickHandler) => void
   options?: Record<string, any> 
 }
 
+
 interface DialogProps {
+  /**
+   * The header text to display in the dialog. If not provided, no header will be displayed.
+   */
   header?: string
+
+  /**
+   * If true, a close button will be displayed in the dialog header. Default is true.
+   */
   headerCloseButton?: boolean
+
+  /**
+   * An array of buttons to display in the dialog footer. 
+   */
   buttons?: DialogButton[]
+
+  /**
+   * If true, clicking outside the dialog will close it. Default is true.
+   * 
+   * @deprecated Use `closeByClickOutside` instead
+   */
   clickToCloseOutside?: boolean
+
+  /**
+   * If true, pressing the Esc key will close the dialog. Default is true.
+   */
+  closeByEsc?: boolean
+
+  /**
+   * If true, clicking outside the dialog will close it. Default is true.
+   */
+  closeByClickOutside?: boolean
+
+  /**
+   * Function that will be called before the dialog is closed. 
+   */
   beforeCloseFunction?: (() => void | Promise<void>) | null
+
+  /**
+   * Function that will be called before the dialog is opened. 
+   */
   beforeOpenFunction?: (() => void | Promise<void>) | null
+
+  /**
+   * Disables close on Ecs button
+   * 
+   * @deprecated Use `closeByEsc` or  instead
+   */
   closable?: boolean
+
+  /**
+   * If true, the dialog will ask for confirmation before closing. Default is false.
+   */
   askForCloseConfirmation?: boolean
+
+  /**
+   * The text to display in the close confirmation dialog. Default is "Are you sure you want to close this dialog?".
+   */
   closeConfirmationText?: string
+
+  /**
+   * If true, the dialog will be removed from the DOM when closed. Default is false.
+   */
+  removeFromDomOnClose?: boolean
 }
 
+
+
+
+
+
+/**********  for the backward compatibility  ***************/
+class Dialog implements IDialogInsideButtonClickHandler {
+  hide: () => void
+  constructor( hide: () => void ) {
+    this.hide = hide;
+  }
+}
+const dialog: Ref<Dialog> = ref(
+  new Dialog(
+    () => {
+      if (dialog.value) {
+        tryToHideModal();
+      }
+    }
+  )
+);
+/*************************************************************/
+
+
+
+const modalRef = ref();
+
 const props = withDefaults(defineProps<DialogProps>(), {
   header: '',
   headerCloseButton: true,
   buttons: () => [],
-  clickToCloseOutside: true,
+  clickToCloseOutside: false,
+  closeByEsc: true,
+  closeByClickOutside: true,
   beforeCloseFunction: null,
   beforeOpenFunction: null,
-  closable: true,
+  closable: false,
   askForCloseConfirmation: false,
   closeConfirmationText: 'Are you sure you want to close this dialog?',
+  removeFromDomOnClose: false,
 })
 
 const buttons = computed<DialogButton[]>(() => {
@@ -129,51 +193,20 @@ const buttons = computed<DialogButton[]>(() => {
     {
       label: 'Close',
       onclick: (dialog: any) => {
-        if (!props.askForCloseConfirmation) {
-          dialog.hide();
-        } else {
-          showConfirmationOnClose.value = true;
-        }
+        tryToHideModal();
       },
       options: {}
     }
   ];
 });
 
-const showConfirmationOnClose = ref(false);
-onMounted(async () => {
-  //await one tick when all is mounted
-  await nextTick();
-  modal.value = new Modal(
-    modalEl.value,
-    {
-      closable: props.closable,
-      backdrop: props.clickToCloseOutside ? 'dynamic' : 'static',
-      onHide: async () => {
-        if (props.beforeCloseFunction) {
-          await props.beforeCloseFunction();
-        }
-      },
-      onShow: async () => {
-        if (props.beforeOpenFunction) {
-          await props.beforeOpenFunction();
-        }
-      },
-    }
-  );
-})
-
-onUnmounted(() => {
-  //destroy tooltip
-  modal.value?.destroy();
-})
 
 function open() {
-  modal.value?.show();
+  modalRef.value.open();
 }
 
 function close() {
-  modal.value?.hide();
+  modalRef.value.hide();
 }
 
 defineExpose({
@@ -183,11 +216,7 @@ defineExpose({
 })
 
 function tryToHideModal() {
-  if (!props.askForCloseConfirmation ) {
-    modal.value?.hide();
-  } else {
-    showConfirmationOnClose.value = true;
-  }
+  modalRef.value?.tryToHideModal();
 }