docs(reorder): add new ionReorderStart, ionReorderMove, ionReorderEnd event playgrounds (#4149)

Co-authored-by: Brandy Smith <[email protected]>

Author: brandyscarney

docs/api/reorder-group.md

@@ -16,27 +16,71 @@ import Slots from '@ionic-internal/component-api/v8/reorder-group/slots.md';
 import EncapsulationPill from '@components/page/api/EncapsulationPill';
 
 
-The reorder group is a container for items using the [reorder](./reorder) component. When the user drags an item and drops it in a new position, the `ionItemReorder` event is dispatched. A handler for this event should be implemented that calls the `complete` method.
+The reorder group is a container for items using the [reorder](./reorder) component. When the user drags an item and drops it, the `ionReorderEnd` event is dispatched. A handler for this event should be implemented that calls the `complete` method.
 
-The `detail` property of the `ionItemReorder` event includes all of the relevant information about the reorder operation, including the `from` and `to` indexes. In the context of reordering, an item moves `from` an index `to` a new index. For example usage of the reorder group, see the [reorder](./reorder) documentation.
+The `detail` property of the `ionReorderEnd` event includes all of the relevant information about the reorder operation, including the `from` and `to` indexes. In the context of reordering, an item moves `from` an index `to` an index. For example usage of the reorder group, see the [reorder](./reorder) documentation.
 
 
 ## Interfaces
 
-### ItemReorderEventDetail
+### ReorderMoveEventDetail
 
 ```typescript
-interface ItemReorderEventDetail {
+interface ReorderMoveEventDetail {
+  from: number;
+  to: number;
+}
+```
+
+### ReorderEndEventDetail
+
+```typescript
+interface ReorderEndEventDetail {
   from: number;
   to: number;
   complete: (data?: boolean | any[]) => any;
 }
 ```
 
-### ItemReorderCustomEvent
+### ReorderMoveCustomEvent
+
+While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component.
+
+```typescript
+interface ReorderMoveCustomEvent extends CustomEvent {
+  detail: ReorderMoveEventDetail;
+  target: HTMLIonReorderGroupElement;
+}
+
+```
+
+### ReorderEndCustomEvent
 
 While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component.
 
+```typescript
+interface ReorderEndCustomEvent extends CustomEvent {
+  detail: ReorderEndEventDetail;
+  target: HTMLIonReorderGroupElement;
+}
+```
+
+### ItemReorderEventDetail (deprecated)
+
+**_Deprecated_** — Use the `ionReorderEnd` event with `ReorderEndEventDetail` instead.
+
+```typescript
+interface ItemReorderEventDetail {
+  from: number;
+  to: number;
+  complete: (data?: boolean | any[]) => any;
+}
+```
+
+### ItemReorderCustomEvent (deprecated)
+
+**_Deprecated_** — Use the `ionReorderEnd` event with `ReorderEndCustomEvent` instead.
+
 ```typescript
 interface ItemReorderCustomEvent extends CustomEvent {
   detail: ItemReorderEventDetail;

docs/api/reorder.md

@@ -20,7 +20,7 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill';
 
 Reorder is a component that allows an item to be dragged to change its order within a group of items. It must be used within a [reorder group](./reorder-group) to provide a visual drag and drop interface.
 
-The reorder is the anchor used to drag and drop the items. Once the reorder is complete, the `ionItemReorder` event will be dispatched from the reorder group and the `complete` method needs to be called.
+The reorder is the anchor used to drag and drop the items. Once the reorder is complete, the `ionReorderEnd` event will be dispatched from the reorder group and the `complete` method needs to be called.
 
 
 ## Basic Usage
@@ -73,6 +73,29 @@ import UpdatingData from '@site/static/usage/v8/reorder/updating-data/index.md';
 
 <UpdatingData />
 
+## Event Handling
+
+### Using `ionReorderStart` and `ionReorderEnd`
+
+The `ionReorderStart` event is emitted when the user begins a reorder gesture. This event fires when the user taps and holds an item, before any movement occurs. This is useful for preparing the UI for the reorder operation, such as hiding certain elements or updating the visual state of items. For example, icons in list items can be hidden while they are being dragged and shown again when the reorder is complete.
+
+The `ionReorderEnd` event is emitted when the user completes the reorder gesture. This occurs when the user releases the item they are dragging, for example by lifting their finger on a touch screen or releasing the mouse button. The event includes the `from` and `to` indices of the item, as well as the `complete` method that should be called to finalize the reorder operation. The `from` index will always be the position of the item when the gesture started, while the `to` index will be its final position. This event will fire even if no items have changed position, in which case the `from` and `to` indices will be the same.
+
+import ReorderStartEndEvents from '@site/static/usage/v8/reorder/reorder-start-end-events/index.md';
+
+<ReorderStartEndEvents />
+
+### Using `ionReorderMove`
+
+The `ionReorderMove` event is emitted continuously during the reorder gesture as the user drags an item. The event includes the `from` and `to` indices of the item. Unlike `ionReorderEnd`, the `from` index in this event represents the last known position of the item (which updates as the item moves), while the `to` index represents its current position. If the item has not changed position since the last event, the `from` and `to` indices will be the same. This event is useful for tracking position changes during the drag operation. For example, the ranking or numbering of items can be updated in real-time as they are being dragged to maintain a logical ascending order.
+
+:::warning
+Do not call the `complete` method during the `ionReorderMove` event as it can break the gesture.
+:::
+
+import ReorderMoveEvent from '@site/static/usage/v8/reorder/reorder-move-event/index.md';
+
+<ReorderMoveEvent />
 
 ## Usage with Virtual Scroll
 

plugins/docusaurus-plugin-ionic-component-api/index.js

@@ -145,7 +145,7 @@ ${properties
   .map((prop) => {
     const isDeprecated = prop.deprecation !== undefined;
 
-    const docs = isDeprecated ? `${prop.docs}\n_Deprecated_ ${prop.deprecation}` : prop.docs;
+    const docs = isDeprecated ? `${prop.docs}\n\n**_Deprecated_** — ${prop.deprecation}` : prop.docs;
 
     return `
 ### ${prop.name} ${isDeprecated ? '(deprecated)' : ''}
@@ -170,7 +170,15 @@ function renderEvents({ events }) {
   return `
 | Name | Description | Bubbles |
 | --- | --- | --- |
-${events.map((event) => `| \`${event.event}\` | ${formatMultiline(event.docs)} | \`${event.bubbles}\` |`).join('\n')}`;
+${events
+  .map((event) => {
+    const isDeprecated = event.deprecation !== undefined;
+    const docs = isDeprecated ? `${event.docs}\n\n**_Deprecated_** — ${event.deprecation}` : event.docs;
+    return `| \`${event.event}\` ${isDeprecated ? '**(deprecated)**' : ''} | ${formatMultiline(docs)} | \`${
+      event.bubbles
+    }\` |`;
+  })
+  .join('\n')}`;
 }
 
 /**

static/demos/api/reorder/index.html

@@ -99,7 +99,7 @@
       function toggleReorder() {
         const reorderGroup = document.getElementById('reorder');
         reorderGroup.disabled = !reorderGroup.disabled;
-        reorderGroup.addEventListener('ionItemReorder', ({ detail }) => {
+        reorderGroup.addEventListener('ionReorderEnd', ({ detail }) => {
           detail.complete(true);
         });
       }

static/usage/v8/reorder/basic/angular/example_component_html.md

@@ -2,7 +2,7 @@
 <ion-list>
   <!-- The reorder gesture is disabled by default, enable it to drag and drop items -->
   <!-- Casting $event to $any is a temporary fix for this bug https://github.com/ionic-team/ionic-framework/issues/24245 -->
-  <ion-reorder-group [disabled]="false" (ionItemReorder)="handleReorder($any($event))">
+  <ion-reorder-group [disabled]="false" (ionReorderEnd)="handleReorderEnd($any($event))">
     <ion-item>
       <ion-label> Item 1 </ion-label>
       <ion-reorder slot="end"></ion-reorder>

static/usage/v8/reorder/basic/angular/example_component_ts.md

@@ -1,12 +1,12 @@
 ```ts
 import { Component } from '@angular/core';
 import {
-  ItemReorderEventDetail,
   IonItem,
   IonLabel,
   IonList,
   IonReorder,
   IonReorderGroup,
+  ReorderEndCustomEvent,
 } from '@ionic/angular/standalone';
 
 @Component({
@@ -16,14 +16,14 @@ import {
   imports: [IonItem, IonLabel, IonList, IonReorder, IonReorderGroup],
 })
 export class ExampleComponent {
-  handleReorder(event: CustomEvent<ItemReorderEventDetail>) {
+  handleReorderEnd(event: ReorderEndCustomEvent) {
     // The `from` and `to` properties contain the index of the item
     // when the drag started and ended, respectively
     console.log('Dragged from index', event.detail.from, 'to', event.detail.to);
 
     // Finish the reorder and position the item in the DOM based on
     // where the gesture ended. This method can also be called directly
-    // by the reorder group
+    // by the reorder group.
     event.detail.complete();
   }
 }

static/usage/v8/reorder/basic/demo.html

@@ -11,7 +11,7 @@
 
     <style>
       ion-list {
-        width: 100%;
+        width: 300px;
       }
     </style>
   </head>
@@ -56,14 +56,14 @@
     <script>
       const reorderGroup = document.querySelector('ion-reorder-group');
 
-      reorderGroup.addEventListener('ionItemReorder', ({ detail }) => {
+      reorderGroup.addEventListener('ionReorderEnd', ({ detail }) => {
         // The `from` and `to` properties contain the index of the item
         // when the drag started and ended, respectively
         console.log('Dragged from index', detail.from, 'to', detail.to);
 
         // Finish the reorder and position the item in the DOM based on
         // where the gesture ended. This method can also be called directly
-        // by the reorder group
+        // by the reorder group.
         detail.complete();
       });
     </script>

static/usage/v8/reorder/basic/javascript.md

@@ -32,14 +32,14 @@
 <script>
   const reorderGroup = document.querySelector('ion-reorder-group');
 
-  reorderGroup.addEventListener('ionItemReorder', ({ detail }) => {
+  reorderGroup.addEventListener('ionReorderEnd', ({ detail }) => {
     // The `from` and `to` properties contain the index of the item
     // when the drag started and ended, respectively
     console.log('Dragged from index', detail.from, 'to', detail.to);
 
     // Finish the reorder and position the item in the DOM based on
     // where the gesture ended. This method can also be called directly
-    // by the reorder group
+    // by the reorder group.
     detail.complete();
   });
 </script>

static/usage/v8/reorder/basic/react.md

@@ -1,23 +1,23 @@
 ```tsx
 import React from 'react';
-import { IonItem, IonLabel, IonList, IonReorder, IonReorderGroup, ItemReorderEventDetail } from '@ionic/react';
+import { IonItem, IonLabel, IonList, IonReorder, IonReorderGroup, ReorderEndCustomEvent } from '@ionic/react';
 
 function Example() {
-  function handleReorder(event: CustomEvent<ItemReorderEventDetail>) {
+  function handleReorderEnd(event: ReorderEndCustomEvent) {
     // The `from` and `to` properties contain the index of the item
     // when the drag started and ended, respectively
     console.log('Dragged from index', event.detail.from, 'to', event.detail.to);
 
     // Finish the reorder and position the item in the DOM based on
     // where the gesture ended. This method can also be called directly
-    // by the reorder group
+    // by the reorder group.
     event.detail.complete();
   }
 
   return (
     <IonList>
       {/* The reorder gesture is disabled by default, enable it to drag and drop items */}
-      <IonReorderGroup disabled={false} onIonItemReorder={handleReorder}>
+      <IonReorderGroup disabled={false} onIonReorderEnd={handleReorderEnd}>
         <IonItem>
           <IonLabel>Item 1</IonLabel>
           <IonReorder slot="end"></IonReorder>

static/usage/v8/reorder/basic/vue.md

@@ -2,7 +2,7 @@
 <template>
   <ion-list>
     <!-- The reorder gesture is disabled by default, enable it to drag and drop items -->
-    <ion-reorder-group :disabled="false" @ionItemReorder="handleReorder($event)">
+    <ion-reorder-group :disabled="false" @ionReorderEnd="handleReorderEnd($event)">
       <ion-item>
         <ion-label> Item 1 </ion-label>
         <ion-reorder slot="end"></ion-reorder>
@@ -32,24 +32,24 @@
 </template>
 
 <script lang="ts">
-  import { IonItem, IonLabel, IonList, IonReorder, IonReorderGroup } from '@ionic/vue';
+  import { IonItem, IonLabel, IonList, IonReorder, IonReorderGroup, ReorderEndCustomEvent } from '@ionic/vue';
   import { defineComponent } from 'vue';
 
   export default defineComponent({
     components: { IonItem, IonLabel, IonList, IonReorder, IonReorderGroup },
     setup() {
-      const handleReorder = (event: CustomEvent) => {
+      const handleReorderEnd = (event: ReorderEndCustomEvent) => {
         // The `from` and `to` properties contain the index of the item
         // when the drag started and ended, respectively
         console.log('Dragged from index', event.detail.from, 'to', event.detail.to);
 
         // Finish the reorder and position the item in the DOM based on
         // where the gesture ended. This method can also be called directly
-        // by the reorder group
+        // by the reorder group.
         event.detail.complete();
       };
 
-      return { handleReorder };
+      return { handleReorderEnd };
     },
   });
 </script>