From 60f2b0d8fb7825b658377fad83b9ac033cf72563 Mon Sep 17 00:00:00 2001
From: Benjamin Canac <canacb1@gmail.com>
Date: Fri, 23 Aug 2024 13:26:20 +0200
Subject: [PATCH] docs(modal): update

---
 .../drawer/DrawerFooterSlotExample.vue        |   2 +-
 .../modal/ModalCommandPaletteExample.vue      |  34 ++
 .../examples/modal/ModalFooterSlotExample.vue |  18 +
 .../examples/modal/ModalNestedExample.vue     |  22 ++
 .../examples/modal/ModalOpenExample.vue       |  17 +
 .../modal/ModalProgrammaticExample.vue        |  20 +
 .../example/ExampleModalComponent.vue         |  15 +
 docs/content/3.components/alert.md            |   2 +-
 docs/content/3.components/collapsible.md      |   4 +
 docs/content/3.components/drawer.md           |  44 ++-
 docs/content/3.components/modal.md            | 341 +++++++++++++++++-
 docs/nuxt.config.ts                           |  13 +-
 src/runtime/components/Drawer.vue             |   4 +
 src/runtime/components/Modal.vue              |  20 +-
 src/runtime/components/Slideover.vue          |  10 +-
 15 files changed, 540 insertions(+), 26 deletions(-)
 create mode 100644 docs/app/components/content/examples/modal/ModalCommandPaletteExample.vue
 create mode 100644 docs/app/components/content/examples/modal/ModalFooterSlotExample.vue
 create mode 100644 docs/app/components/content/examples/modal/ModalNestedExample.vue
 create mode 100644 docs/app/components/content/examples/modal/ModalOpenExample.vue
 create mode 100644 docs/app/components/content/examples/modal/ModalProgrammaticExample.vue
 create mode 100644 docs/app/components/example/ExampleModalComponent.vue

diff --git a/docs/app/components/content/examples/drawer/DrawerFooterSlotExample.vue b/docs/app/components/content/examples/drawer/DrawerFooterSlotExample.vue
index afe5a154..1184afcb 100644
--- a/docs/app/components/content/examples/drawer/DrawerFooterSlotExample.vue
+++ b/docs/app/components/content/examples/drawer/DrawerFooterSlotExample.vue
@@ -3,7 +3,7 @@ const open = ref(false)
 </script>
 
 <template>
-  <UDrawer v-model:open="open" title="Drawer with actions" description="This is useful when you want a form in a drawer.">
+  <UDrawer v-model:open="open" title="Drawer with footer" description="This is useful when you want a form in a Drawer.">
     <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
 
     <template #body>
diff --git a/docs/app/components/content/examples/modal/ModalCommandPaletteExample.vue b/docs/app/components/content/examples/modal/ModalCommandPaletteExample.vue
new file mode 100644
index 00000000..625e066e
--- /dev/null
+++ b/docs/app/components/content/examples/modal/ModalCommandPaletteExample.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+const searchTerm = ref('')
+
+const { data: users, status } = await useFetch('https://jsonplaceholder.typicode.com/users', {
+  params: { q: searchTerm },
+  transform: (data: any[]) => {
+    return data?.map(user => ({ id: user.id, label: user.name, suffix: user.email, avatar: { src: `https://i.pravatar.cc/120?img=${user.id}` } })) || []
+  },
+  lazy: true
+})
+
+const groups = computed(() => [{
+  id: 'users',
+  label: searchTerm.value ? `Users matching “${searchTerm.value}”...` : 'Users',
+  items: users.value || [],
+  filter: false
+}])
+</script>
+
+<template>
+  <UModal>
+    <UButton label="Search users..." color="gray" variant="subtle" icon="i-heroicons-magnifying-glass" />
+
+    <template #content>
+      <UCommandPalette
+        v-model:search-term="searchTerm"
+        :loading="status === 'pending'"
+        :groups="groups"
+        placeholder="Search users..."
+        class="h-96 border-t border-gray-200 dark:border-gray-800"
+      />
+    </template>
+  </UModal>
+</template>
diff --git a/docs/app/components/content/examples/modal/ModalFooterSlotExample.vue b/docs/app/components/content/examples/modal/ModalFooterSlotExample.vue
new file mode 100644
index 00000000..f0117fca
--- /dev/null
+++ b/docs/app/components/content/examples/modal/ModalFooterSlotExample.vue
@@ -0,0 +1,18 @@
+<script setup lang="ts">
+const open = ref(false)
+</script>
+
+<template>
+  <UModal v-model:open="open" title="Modal with footer" description="This is useful when you want a form in a Modal." :ui="{ footer: 'justify-end' }">
+    <UButton label="Open" color="gray" variant="subtle" />
+
+    <template #body>
+      <Placeholder class="h-48" />
+    </template>
+
+    <template #footer>
+      <UButton label="Cancel" color="gray" variant="outline" @click="open = false" />
+      <UButton label="Submit" color="gray" />
+    </template>
+  </UModal>
+</template>
diff --git a/docs/app/components/content/examples/modal/ModalNestedExample.vue b/docs/app/components/content/examples/modal/ModalNestedExample.vue
new file mode 100644
index 00000000..40333493
--- /dev/null
+++ b/docs/app/components/content/examples/modal/ModalNestedExample.vue
@@ -0,0 +1,22 @@
+<script setup lang="ts">
+const first = ref(false)
+const second = ref(false)
+</script>
+
+<template>
+  <UModal v-model:open="first" title="First modal" :ui="{ footer: 'justify-end' }">
+    <UButton color="gray" variant="subtle" label="Open" />
+
+    <template #footer>
+      <UButton label="Close" color="gray" variant="outline" @click="first = false" />
+
+      <UModal v-model:open="second" title="Second modal" :ui="{ footer: 'justify-end' }">
+        <UButton label="Open second" color="gray" />
+
+        <template #footer>
+          <UButton label="Close" color="gray" variant="outline" @click="second = false" />
+        </template>
+      </UModal>
+    </template>
+  </UModal>
+</template>
diff --git a/docs/app/components/content/examples/modal/ModalOpenExample.vue b/docs/app/components/content/examples/modal/ModalOpenExample.vue
new file mode 100644
index 00000000..067a060e
--- /dev/null
+++ b/docs/app/components/content/examples/modal/ModalOpenExample.vue
@@ -0,0 +1,17 @@
+<script setup lang="ts">
+const open = ref(false)
+
+defineShortcuts({
+  o: () => open.value = !open.value
+})
+</script>
+
+<template>
+  <UModal v-model:open="open">
+    <UButton label="Open" color="gray" variant="subtle" />
+
+    <template #content>
+      <Placeholder class="h-48 m-4" />
+    </template>
+  </UModal>
+</template>
diff --git a/docs/app/components/content/examples/modal/ModalProgrammaticExample.vue b/docs/app/components/content/examples/modal/ModalProgrammaticExample.vue
new file mode 100644
index 00000000..97413450
--- /dev/null
+++ b/docs/app/components/content/examples/modal/ModalProgrammaticExample.vue
@@ -0,0 +1,20 @@
+<script setup lang="ts">
+import { LazyExampleModalComponent } from '#components'
+
+const count = ref(0)
+
+const modal = useModal()
+
+function openModal() {
+  count.value++
+
+  modal.open(LazyExampleModalComponent, {
+    description: 'And you can even provide a description !',
+    count: count.value
+  })
+}
+</script>
+
+<template>
+  <UButton label="Open" color="gray" variant="subtle" @click="openModal" />
+</template>
diff --git a/docs/app/components/example/ExampleModalComponent.vue b/docs/app/components/example/ExampleModalComponent.vue
new file mode 100644
index 00000000..f5aa2d39
--- /dev/null
+++ b/docs/app/components/example/ExampleModalComponent.vue
@@ -0,0 +1,15 @@
+<script lang="ts" setup>
+const modal = useModal()
+
+defineProps<{
+  count: number
+}>()
+</script>
+
+<template>
+  <UModal :title="`This modal was opened programmatically ${count} times`">
+    <template #footer>
+      <UButton color="gray" label="Close" @click="modal.close()" />
+    </template>
+  </UModal>
+</template>
diff --git a/docs/content/3.components/alert.md b/docs/content/3.components/alert.md
index 5aad902e..1431da54 100644
--- a/docs/content/3.components/alert.md
+++ b/docs/content/3.components/alert.md
@@ -129,7 +129,7 @@ props:
 ::
 
 ::tip
-You can customize this icon globally in your `app.config.ts` under `ui.icons.loading` key.
+You can customize this icon globally in your `app.config.ts` under `ui.icons.close` key.
 ::
 
 You can pass all the props of the [Button](/components/button) component to customize it.
diff --git a/docs/content/3.components/collapsible.md b/docs/content/3.components/collapsible.md
index bd776242..1d5ce391 100644
--- a/docs/content/3.components/collapsible.md
+++ b/docs/content/3.components/collapsible.md
@@ -39,6 +39,10 @@ class: 'justify-center'
 In this example, press :kbd{value="O"} to toggle the Collapsible.
 ::
 
+::tip
+This allows you to move the trigger outside of the Collapsible or remove it entirely.
+::
+
 ### With rotating icon
 
 Here is an example with a rotating icon in the Button that indicates the open state of the Collapsible.
diff --git a/docs/content/3.components/drawer.md b/docs/content/3.components/drawer.md
index f420b348..3b8b82b8 100644
--- a/docs/content/3.components/drawer.md
+++ b/docs/content/3.components/drawer.md
@@ -26,7 +26,7 @@ slots:
 
   content: |
 
-    <Placeholder class="h-48" />
+    <Placeholder class="h-48 m-4" />
 ---
 
 :u-button{label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}
@@ -35,7 +35,7 @@ slots:
 :placeholder{class="h-48 m-4"}
 ::
 
-You can also use the `#header`, `#body` and `#footer` slots to customize the Drawer's content.
+You can also use the `#header`{lang="ts-type"}, `#body`{lang="ts-type"} and `#footer`{lang="ts-type"} slots to customize the Drawer's content.
 
 ### Title
 
@@ -46,7 +46,7 @@ Use the `title` prop to set the title of the Drawer's header.
 prettier: true
 class: 'justify-center'
 props:
-  title: 'Title'
+  title: 'Drawer with title'
 slots:
   default: |
 
@@ -74,7 +74,7 @@ class: 'justify-center'
 ignore:
   - title
 props:
-  title: 'Title'
+  title: 'Drawer with description'
   description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
 slots:
   default: |
@@ -92,6 +92,32 @@ slots:
 :placeholder{class="h-48"}
 ::
 
+### Overlay
+
+Use the `overlay` prop to control whether the Drawer has an overlay or not. Defaults to `true`.
+
+::component-code
+---
+prettier: true
+class: 'justify-center'
+props:
+  overlay: false
+slots:
+  default: |
+
+    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
+
+  content: |
+
+    <Placeholder class="h-48 m-4" />
+---
+
+:u-button{label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}
+
+#content
+:placeholder{class="h-48 m-4"}
+::
+
 ### Scale background
 
 Use the `should-scale-background` prop to scale the background when the Drawer is open, creating a visual depth effect.
@@ -105,14 +131,14 @@ props:
 slots:
   default: |
 
-    <UButton label="Open with scale" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
+    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
 
   content: |
 
-    <Placeholder class="h-48" />
+    <Placeholder class="h-48 m-4" />
 ---
 
-:u-button{label="Open with scale" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}
+:u-button{label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}
 
 #content
 :placeholder{class="h-screen m-4"}
@@ -162,6 +188,10 @@ class: 'justify-center'
 In this example, press :kbd{value="O"} to toggle the Drawer.
 ::
 
+::tip
+This allows you to move the trigger outside of the Drawer or remove it entirely.
+::
+
 ### With footer slot
 
 Use the `#footer` slot to add content after the Drawer's body.
diff --git a/docs/content/3.components/modal.md b/docs/content/3.components/modal.md
index 50cc33af..e423a029 100644
--- a/docs/content/3.components/modal.md
+++ b/docs/content/3.components/modal.md
@@ -7,15 +7,350 @@ links:
   - label: GitHub
     icon: i-simple-icons-github
     to: https://github.com/benjamincanac/ui3/tree/dev/src/runtime/components/Modal.vue
-navigation:
-  badge:
-    label: Todo
 ---
 
 ## Usage
 
+Use a [Button](/components/button) or any other component in the default slot of the Modal.
+
+Then, use the `#content` slot to add the content displayed when the Modal is open.
+
+::component-code
+---
+prettier: true
+class: 'justify-center'
+slots:
+  default: |
+
+    <UButton label="Open" color="gray" variant="subtle" />
+
+  content: |
+
+    <Placeholder class="h-48 m-4" />
+---
+
+:u-button{label="Open" color="gray" variant="subtle"}
+
+#content
+:placeholder{class="h-48 m-4"}
+::
+
+You can also use the `#header`{lang="ts-type"}, `#body`{lang="ts-type"} and `#footer`{lang="ts-type"} slots to customize the Modal's content.
+
+### Title
+
+Use the `title` prop to set the title of the Modal's header.
+
+::component-code
+---
+prettier: true
+class: 'justify-center'
+props:
+  title: 'Modal with title'
+slots:
+  default: |
+
+    <UButton label="Open" color="gray" variant="subtle" />
+
+  body: |
+
+    <Placeholder class="h-48" />
+---
+
+:u-button{label="Open" color="gray" variant="subtle"}
+
+#body
+:placeholder{class="h-48"}
+::
+
+### Description
+
+Use the `description` prop to set the description of the Modal's header.
+
+::component-code
+---
+prettier: true
+class: 'justify-center'
+ignore:
+  - title
+props:
+  title: 'Modal with description'
+  description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+slots:
+  default: |
+
+    <UButton label="Open" color="gray" variant="subtle" />
+
+  body: |
+
+    <Placeholder class="h-48" />
+---
+
+:u-button{label="Open" color="gray" variant="subtle"}
+
+#body
+:placeholder{class="h-48"}
+::
+
+### Close
+
+Use the `close` prop to customize or hide the close button displayed in the Modal's header. You can pass all the props of the [Button](/components/button) component to customize it.
+
+::tip
+The close button is not displayed if the `#content` slot is used as it's a part of the header.
+::
+
+Use the `close-icon` prop to customize the button [Icon](/components/icon). Defaults to `i-heroicons-x-mark-20-solid`.
+
+::component-code
+---
+prettier: true
+class: 'justify-center'
+ignore:
+  - title
+  - close.color
+  - close.variant
+props:
+  title: 'Modal with close button'
+  close:
+    color: primary
+    variant: outline
+    class: 'rounded-full'
+  closeIcon: ''
+slots:
+  default: |
+
+    <UButton label="Open" color="gray" variant="subtle" />
+
+  body: |
+
+    <Placeholder class="h-48" />
+---
+
+:u-button{label="Open" color="gray" variant="subtle"}
+
+#body
+:placeholder{class="h-48"}
+::
+
+::tip
+You can customize this icon globally in your `app.config.ts` under `ui.icons.close` key.
+::
+
+### Overlay
+
+Use the `overlay` prop to control whether the Modal has an overlay or not. Defaults to `true`.
+
+::component-code
+---
+prettier: true
+ignore:
+  - title
+class: 'justify-center'
+props:
+  overlay: false
+  title: 'Modal fullscreen'
+slots:
+  default: |
+
+    <UButton label="Open" color="gray" variant="subtle" />
+
+  body: |
+
+    <Placeholder class="h-48" />
+---
+
+:u-button{label="Open" color="gray" variant="subtle"}
+
+#body
+:placeholder{class="h-48"}
+::
+
+### Transition
+
+Use the `transition` prop to control whether the Modal is animated or not. Defaults to `true`.
+
+::component-code
+---
+prettier: true
+ignore:
+  - title
+class: 'justify-center'
+props:
+  transition: false
+  title: 'Modal fullscreen'
+slots:
+  default: |
+
+    <UButton label="Open" color="gray" variant="subtle" />
+
+  body: |
+
+    <Placeholder class="h-48" />
+---
+
+:u-button{label="Open" color="gray" variant="subtle"}
+
+#body
+:placeholder{class="h-48"}
+::
+
+### Fullscreen
+
+Use the `fullscreen` prop to make the Modal fullscreen.
+
+::component-code
+---
+prettier: true
+ignore:
+  - title
+  - fullscreen
+class: 'justify-center'
+props:
+  fullscreen: true
+  title: 'Modal fullscreen'
+slots:
+  default: |
+
+    <UButton label="Open" color="gray" variant="subtle" />
+
+  body: |
+
+    <Placeholder class="h-full" />
+---
+
+:u-button{label="Open" color="gray" variant="subtle"}
+
+#body
+:placeholder{class="h-full"}
+::
+
+### Prevent close
+
+Use the `prevent-close` prop to prevent the Modal from being closed when clicking outside of it.
+
+::component-code
+---
+prettier: true
+ignore:
+  - title
+  - preventClose
+class: 'justify-center'
+props:
+  preventClose: true
+  title: 'Modal prevent close'
+slots:
+  default: |
+
+    <UButton label="Open" color="gray" variant="subtle" />
+
+  body: |
+
+    <Placeholder class="h-48" />
+---
+
+:u-button{label="Open" color="gray" variant="subtle"}
+
+#body
+:placeholder{class="h-48"}
+::
+
 ## Examples
 
+### Control open state
+
+You can control the open state by using the `default-open` prop or the `v-model:open` directive.
+
+::component-example
+---
+name: 'modal-open-example'
+class: 'justify-center'
+---
+::
+
+::note
+In this example, press :kbd{value="O"} to toggle the Modal.
+::
+
+::tip
+This allows you to move the trigger outside of the Modal or remove it entirely.
+::
+
+### Control programatically
+
+You can use the `useModal` composable to open a Modal programatically.
+
+::important
+Make sure to wrap your app with the [`App`](/components/app) component that instantiates the `ModalProvider` component.
+::
+
+First, create a modal component that will be opened programatically:
+
+```vue [ExampleModalComponent.vue]
+<script lang="ts" setup>
+const modal = useModal()
+
+defineProps<{
+  count: number
+}>()
+</script>
+
+<template>
+  <UModal :title="`This modal was opened programmatically ${count} times`">
+    <template #footer>
+      <UButton color="gray" label="Close" @click="modal.close()" />
+    </template>
+  </UModal>
+</template>
+```
+
+Then, use it in your app:
+
+::component-example
+---
+name: 'modal-programmatic-example'
+class: 'justify-center'
+---
+::
+
+::tip
+You can close the modal within the modal component by calling `modal.close()`.
+::
+
+### Nested modals
+
+You can nest modals within each other.
+
+::component-example
+---
+name: 'modal-nested-example'
+class: 'justify-center'
+---
+::
+
+### With footer slot
+
+Use the `#footer` slot to add content after the Modal's body.
+
+::component-example
+---
+name: 'modal-footer-slot-example'
+class: 'justify-center'
+---
+::
+
+### With command palette
+
+You can use the [CommandPalette](/components/command-palette) component inside the Modal.
+
+::component-example
+---
+collapse: true
+name: 'modal-command-palette-example'
+class: 'justify-center'
+---
+::
+
 ## API
 
 ### Props
diff --git a/docs/nuxt.config.ts b/docs/nuxt.config.ts
index dc11c3a5..26f33187 100644
--- a/docs/nuxt.config.ts
+++ b/docs/nuxt.config.ts
@@ -76,9 +76,9 @@ export default defineNuxtConfig({
   nitro: {
     prerender: {
       routes: [
-        '/getting-started',
-        '/api/releases.json',
-        '/api/pulls.json'
+        '/getting-started'
+        // '/api/releases.json',
+        // '/api/pulls.json'
       ],
       ignore: !process.env.NUXT_GITHUB_TOKEN ? ['/pro'] : []
     }
@@ -135,6 +135,7 @@ export default defineNuxtConfig({
         'UInput',
         'UKbd',
         'ULink',
+        'UModal',
         'UProgress',
         'URadioGroup',
         'USlider',
@@ -148,12 +149,6 @@ export default defineNuxtConfig({
     }
   },
 
-  // vite: {
-  //   optimizeDeps: {
-  //     include: ['date-fns']
-  //   }
-  // },
-
   site: {
     url: 'https://ui3.nuxt.com'
   },
diff --git a/src/runtime/components/Drawer.vue b/src/runtime/components/Drawer.vue
index afee90f9..501420b6 100644
--- a/src/runtime/components/Drawer.vue
+++ b/src/runtime/components/Drawer.vue
@@ -20,6 +20,10 @@ export interface DrawerProps extends Pick<DrawerRootProps, 'activeSnapPoint' | '
   description?: string
   /** The content of the drawer. */
   content?: Omit<DialogContentProps, 'as' | 'asChild' | 'forceMount'>
+  /**
+   * Render an overlay behind the drawer.
+   * @defaultValue true
+   */
   overlay?: boolean
   /**
    * Render the drawer in a portal.
diff --git a/src/runtime/components/Modal.vue b/src/runtime/components/Modal.vue
index c668cd29..2b77f917 100644
--- a/src/runtime/components/Modal.vue
+++ b/src/runtime/components/Modal.vue
@@ -15,8 +15,20 @@ export interface ModalProps extends DialogRootProps {
   description?: string
   /** The content of the modal. */
   content?: Omit<DialogContentProps, 'as' | 'asChild' | 'forceMount'>
+  /**
+   * Render an overlay behind the modal.
+   * @defaultValue true
+   */
   overlay?: boolean
+  /**
+   * Animate the modal when opening or closing.
+   * @defaultValue true
+   */
   transition?: boolean
+  /**
+   * When `true`, the modal will take up the full screen.
+   * @defaultValue false
+   */
   fullscreen?: boolean
   /**
    * Render the modal in a portal.
@@ -34,7 +46,10 @@ export interface ModalProps extends DialogRootProps {
    * @defaultValue appConfig.ui.icons.close
    */
   closeIcon?: string
-  /** When `true`, the modal will not close when clicking outside. */
+  /**
+   * When `true`, the modal will not close when clicking outside.
+   * @defaultValue false
+   */
   preventClose?: boolean
   class?: any
   ui?: Partial<typeof modal.slots>
@@ -65,7 +80,8 @@ const props = withDefaults(defineProps<ModalProps>(), {
   close: true,
   portal: true,
   overlay: true,
-  transition: true
+  transition: true,
+  modal: true
 })
 const emits = defineEmits<ModalEmits>()
 const slots = defineSlots<ModalSlots>()
diff --git a/src/runtime/components/Slideover.vue b/src/runtime/components/Slideover.vue
index baded510..4b0c9ea2 100644
--- a/src/runtime/components/Slideover.vue
+++ b/src/runtime/components/Slideover.vue
@@ -18,12 +18,12 @@ export interface SlideoverProps extends DialogRootProps {
   /** The content of the slideover. */
   content?: Omit<DialogContentProps, 'as' | 'asChild' | 'forceMount'>
   /**
-   * Display an overlay behind the slideover.
+   * Render an overlay behind the slideover.
    * @defaultValue true
    */
   overlay?: boolean
   /**
-   * Open & close the slideover with a transition.
+   * Animate the slideover when opening or closing.
    * @defaultValue true
    */
   transition?: boolean
@@ -44,7 +44,10 @@ export interface SlideoverProps extends DialogRootProps {
    * @defaultValue appConfig.ui.icons.close
    */
   closeIcon?: string
-  /** When `true`, the slideover will not close when clicking outside. */
+  /**
+   * When `true`, the slideover will not close when clicking outside.
+   * @defaultValue false
+   */
   preventClose?: boolean
   class?: any
   ui?: Partial<typeof slideover.slots>
@@ -76,6 +79,7 @@ const props = withDefaults(defineProps<SlideoverProps>(), {
   portal: true,
   overlay: true,
   transition: true,
+  modal: true,
   side: 'right'
 })
 const emits = defineEmits<SlideoverEmits>()