From 2b4e88d72749c88a844598e340faeff488c04d9c Mon Sep 17 00:00:00 2001
From: Eugen Istoc <eugenistoc@gmail.com>
Date: Mon, 10 Mar 2025 09:08:57 -0400
Subject: [PATCH] docs(migration): describe `useToast` and `useOverlay` (#3509)

Co-authored-by: Benjamin Canac <canacb1@gmail.com>
---
 docs/content/1.getting-started/2.migration.md | 78 ++++++++++++++++++-
 1 file changed, 77 insertions(+), 1 deletion(-)

diff --git a/docs/content/1.getting-started/2.migration.md b/docs/content/1.getting-started/2.migration.md
index 8859b6a2..30705228 100644
--- a/docs/content/1.getting-started/2.migration.md
+++ b/docs/content/1.getting-started/2.migration.md
@@ -439,7 +439,10 @@ This change affects the following components: `Modal`, `Popover`, `Slideover`, `
 This change affects the following components: `Modal`, `Slideover`.
 ::
 
-6. The `Toast` component `timeout` prop has been renamed to `duration`:
+
+### Changed composables
+
+1. The `useToast()` composable `timeout` prop has been renamed to `duration`:
 
 ```diff
 <script setup lang="ts">
@@ -450,6 +453,79 @@ const toast = useToast()
 </script>
 ```
 
+2. The `useModal` and `useSlideover` composables have been removed in favor of a more generic `useOverlay` composable:
+
+Some important differences:
+- The `useOverlay` composable is now used to create overlay instances
+- Overlays that are opened, can be awaited for their result
+- Overlays can no longer be closed using `modal.close()` or `slideover.close()`, rather, they close automatically: either when a `closed` event is fired explicitly from the opened component OR when the overlay closes itself (clicking on backdrop, pressing the ESC key, etc)
+- To capture the return value in the parent component you explictly emit a `closed` event with the desired value
+
+
+```diff
+<script setup lang="ts">
+import { ModalExampleComponent } from '#components'
+
+- const modal = useModal()
++ const overlay = useOverlay()
+
+- modal.open(ModalExampleComponent)
++ const modal = overlay.create(ModalExampleComponent)
+</script>
+```
+
+Props are now passed through a props attribute:
+
+```diff
+<script setup lang="ts">
+import { ModalExampleComponent } from '#components'
+
+- const modal = useModal()
++ const overlay = useOverlay()
+
+const count = ref(0)
+
+- modal.open(ModalExampleComponent, {
+-   count: count.value
+- })
++ const modal = overlay.create(ModalExampleComponent, {
++   props: {
++     count: count.value
++   }
++ })
+</script>
+```
+
+Closing a modal is now done through the `closed` event. The `modal.open` method now returns a promise that resolves to the result of the modal whenever the modal is closed:
+
+```diff
+<script setup lang="ts">
+import { ModalExampleComponent } from '#components'
+
+- const modal = useModal()
++ const overlay = useOverlay()
+
++ const modal = overlay.create(ModalExampleComponent)
+
+- function openModal() {
+-   modal.open(ModalExampleComponent, {
+-     onSuccess() {
+-       toast.add({ title: 'Success!' })
+-     }
+-   })
+- }
++ async function openModal() {
++   const result = await modal.open(ModalExampleComponent, {
++     count: count.value
++   })
++
++   if (result) {
++     toast.add({ title: 'Success!' })
++   }
++ }
+</script>
+```
+
 ---
 
 ::warning