docs(modal): update playgrounds and add interface

Author: thetaPC

docs/api/modal.md

@@ -265,6 +265,59 @@ interface ModalCustomEvent extends CustomEvent {
 }
 ```
 
+### ModalDragEventDetail
+
+When using the `ionDragMove` and `ionDragEnd` events, the event detail contains the following properties:
+
+```typescript
+interface ModalDragEventDetail {
+  /**
+   * The current Y position of the modal.
+   * 
+   * This can be used to determine how far the modal has been dragged.
+   */
+  currentY: number;
+  /**
+   * The change in Y position since the last event.
+   * 
+   * This can be used to determine the direction of the drag.
+   */
+  deltaY: number;
+  /**
+   * The velocity of the drag in the Y direction.
+   * 
+   * This can be used to determine how fast the modal is being dragged.
+   */
+  velocityY: number;
+  /**
+   * A number between 0 and 1.
+   * 
+   * In a sheet modal, progress represents the relative position between
+   * the lowest and highest defined breakpoints.
+   * 
+   * In a card modal, it measures the relative position between the
+   * bottom of the screen and the top of the modal when it is fully
+   * open.
+   * 
+   * This can be used to style content based on how far the modal has
+   * been dragged.
+   */
+  progress: number;
+  /**
+   * If the modal is a sheet modal, this will be the breakpoint that 
+   * the modal will snap to if the user lets go of the modal at the
+   * current moment.
+   * 
+   * If it's a card modal, this property will not be included in the
+   * event payload.
+   * 
+   * This can be used to style content based on where the modal will
+   * snap to upon release.
+   */
+  currentBreakpoint?: number;
+}
+```
+
 ## Accessibility
 
 ### Keyboard Interactions

static/usage/v8/modal/card/drag-events/angular/example_component_ts.md

@@ -1,7 +1,7 @@
 ```ts
 import { Component, ElementRef, ViewChild, OnInit } from '@angular/core';
 import { IonHeader, IonToolbar, IonTitle, IonContent, IonButton, IonModal, IonLabel } from '@ionic/angular/standalone';
-import type { ModalDragEventDetail } from '@ionic/core';
+import type { ModalDragEventDetail } from '@ionic/angular/standalone';
 
 @Component({
   selector: 'app-example',

static/usage/v8/modal/card/drag-events/vue.md

@@ -10,7 +10,6 @@
       <ion-button id="open-modal" expand="block">Open Card Modal</ion-button>
 
       <ion-modal
-        ref="modal"
         trigger="open-modal"
         :presenting-element="presentingElement"
         @willPresent="onWillPresent()"
@@ -39,30 +38,29 @@ import { ref, onMounted } from 'vue';
 import { IonPage, IonModal, IonHeader, IonToolbar, IonTitle, IonContent, IonButton, IonLabel } from '@ionic/vue';
 import type { ModalDragEventDetail } from '@ionic/vue';
 
-const modal = ref();
-const page = ref<HTMLDivElement | null>(null);
-const presentingElement = ref<HTMLElement | null>(null);
+const page = ref<InstanceType<typeof IonPage>>();
+const presentingElement = ref<HTMLElement>();
 
 const DARKEST_PERCENT = 50;
 const BRIGHTNESS_RANGE = 100 - DARKEST_PERCENT;
 
 onMounted(() => {
-  presentingElement.value = page.value.$el;
+  presentingElement.value = page.value!.$el;
 });
 
 /**
  * Sync the background dimming with the modal's entry animation.
  */
 const onWillPresent = () => {
-  const appEl = page.value.$el;
+  const appEl = page.value!.$el;
 
   appEl.style.transition = 'filter 0.4s ease';
   // Set to max darkness immediately
   appEl.style.setProperty('filter', `brightness(${DARKEST_PERCENT}%)`, 'important');
 };
 
 const onDragStart = () => {
-  const appEl = page.value.$el;
+  const appEl = page.value!.$el;
 
   // Ensure transitions are off during the active drag
   appEl.style.transition = 'none';
@@ -72,7 +70,7 @@ const onDragMove = (event: CustomEvent<ModalDragEventDetail>) => {
   // `progress` is a value from 1 (top) to 0 (bottom)
   const { progress } = event.detail;
 
-  const appEl = page.value.$el;
+  const appEl = page.value!.$el;
   /**
    * Calculate the current brightness based on how far the user has
    * dragged.
@@ -90,7 +88,7 @@ const onDragEnd = (event: CustomEvent<ModalDragEventDetail>) => {
   // `progress` is a value from 1 (top) to 0 (bottom)
   const { progress } = event.detail;
 
-  const appEl = page.value.$el;
+  const appEl = page.value!.$el;
   /**
    * Snap the background brightness based on the user's drag intent.
    * Progress > 0.4 implies an intent to open (snap dark),
@@ -106,7 +104,7 @@ const onDragEnd = (event: CustomEvent<ModalDragEventDetail>) => {
 };
 
 const onWillDismiss = () => {
-  const appEl = page.value.$el;
+  const appEl = page.value!.$el;
 
   // Clean up styles when the modal is dismissed
   appEl.style.removeProperty('filter');

static/usage/v8/modal/sheet/drag-events/angular/example_component_ts.md

@@ -1,7 +1,7 @@
 ```ts
 import { Component, ElementRef, ViewChild } from '@angular/core';
 import { IonButton, IonContent, IonHeader, IonLabel, IonModal, IonTitle, IonToolbar } from '@ionic/angular/standalone';
-import type { ModalDragEventDetail } from '@ionic/core';
+import type { ModalDragEventDetail } from '@ionic/angular/standalone';
 
 @Component({
   selector: 'app-example',

static/usage/v8/modal/sheet/drag-events/vue.md

@@ -31,13 +31,13 @@ import { ref } from 'vue';
 import { IonButton, IonModal, IonHeader, IonContent, IonToolbar, IonTitle, IonLabel } from '@ionic/vue';
 import type { ModalDragEventDetail } from '@ionic/vue';
 
-const modal = ref();
+const modal = ref<InstanceType<typeof IonModal>>();
 
 let baseOpacity: number;
 const MAX_OPACITY = 0.8;
 
 const onDragStart = () => {
-  const modalEl = modal.value.$el;
+  const modalEl = modal.value!.$el;
   const style = window.getComputedStyle(modalEl);
 
   // Fetch the current variable value
@@ -50,7 +50,7 @@ const onDragStart = () => {
 const onDragMove = (event: CustomEvent<ModalDragEventDetail>) => {
   // `progress` is a value from 1 (top) to 0 (bottom)
   const { progress } = event.detail;
-  const modalEl = modal.value.$el;
+  const modalEl = modal.value!.$el;
   const initialBreakpoint = modalEl.initialBreakpoint || 0.25;
   let dynamicOpacity: number;
 
@@ -99,7 +99,7 @@ const onDragMove = (event: CustomEvent<ModalDragEventDetail>) => {
 const onDragEnd = (event: CustomEvent<ModalDragEventDetail>) => {
   // `currentBreakpoint` tells us which snap point the modal will animate to after the drag ends
   const { currentBreakpoint } = event.detail;
-  const modalEl = modal.value.$el;
+  const modalEl = modal.value!.$el;
 
   /**
    * If the modal is snapping to the closed state (0), reset the
@@ -117,7 +117,7 @@ const onDragEnd = (event: CustomEvent<ModalDragEventDetail>) => {
    * visual effect.
    */
   if (currentBreakpoint === 1) {
-    targetOpacity = this.MAX_OPACITY;
+    targetOpacity = MAX_OPACITY;
   }
 
   // Re-enable transition for a smooth snap-back