fix(useOverlay): improve types and docs (#4012)

Co-authored-by: Benjamin Canac <canacb1@gmail.com>

docs/content/1.getting-started/2.migration.md

@@ -504,7 +504,7 @@ const count = ref(0)
 </script>
 ```
 
-Closing a modal is now done through the `close` event. The `modal.open` method now returns a promise that resolves to the result of the modal whenever the modal is close:
+Closing a modal is now done through the `close` event. The `modal.open` method now returns an instance that can be used to await for the result of the modal whenever the modal is closed:
 
 ```diff
 <script setup lang="ts">
@@ -523,10 +523,12 @@ import { ModalExampleComponent } from '#components'
 -   })
 - }
 + async function openModal() {
-+   const result = await modal.open(ModalExampleComponent, {
++   const instance = modal.open(ModalExampleComponent, {
 +     count: count.value
 +   })
 +
++   const result = await instance.result
++
 +   if (result) {
 +     toast.add({ title: 'Success!' })
 +   }

docs/content/2.composables/use-overlay.md

@@ -22,14 +22,14 @@ async function openModal() {
 - The `useOverlay` composable is created using `createSharedComposable`, ensuring that the same overlay state is shared across your entire application.
 
 ::note
-In order to return a value from the overlay, the `overlay.open()` can be awaited. In order for this to work, however, the **overlay component must emit a `close` event**. See example below for details.
+In order to return a value from the overlay, the `overlay.open().instance.result` can be awaited. In order for this to work, however, the **overlay component must emit a `close` event**. See example below for details.
 ::
 
 ## API
 
 ### `create(component: T, options: OverlayOptions): OverlayInstance`
 
-Creates an overlay, and returns its instance
+Creates an overlay, and returns a factory instance
 
 - Parameters:
   - `component`: The overlay component
@@ -38,7 +38,7 @@ Creates an overlay, and returns its instance
     - `props?: ComponentProps`: An optional object of props to pass to the rendered component.
     - `destroyOnClose?: boolean` Removes the overlay from memory when closed `default: false`
 
-### `open(id: symbol, props?: ComponentProps<T>): Promise<any>`
+### `open(id: symbol, props?: ComponentProps<T>): OpenedOverlay<T>`
 
 Opens the overlay using its `id`
 
@@ -75,7 +75,7 @@ In-memory list of overlays that were created
 
 ## Overlay Instance API
 
-### `open(props?: ComponentProps<T>): Promise<any>`
+### `open(props?: ComponentProps<T>): Promise<OpenedOverlay<T>>`
 
 Opens the overlay
 
@@ -138,7 +138,7 @@ const overlay = useOverlay()
 
 // Create with default props
 const modalA = overlay.create(ModalA, { title: 'Welcome' })
-const modalB = overlay.create(modalB)
+const modalB = overlay.create(ModalB)
 
 const slideoverA = overlay.create(SlideoverA)
 
@@ -149,7 +149,9 @@ const openModalA = () => {
 
 const openModalB = async () => {
   // Open modalB, and wait for its result
-  const input = await modalB.open()
+  const modalBInstance = modalB.open()
+
+  const input = await modalBInstance.result
 
   // Pass the result from modalB to the slideover, and open it.
   slideoverA.open({ input })