docs(reorder): assign stable identity to loop items (#3239)

Author: liamdebeasi

docs/api/reorder.md

@@ -61,10 +61,14 @@ import Wrapper from '@site/static/usage/v7/reorder/wrapper/index.md';
 
 ## Updating Data
 
-When the `complete` method is called on the reorder group with no parameters, the DOM nodes will be reordered. If the items are rendered from an array of data that needs to be sorted, this can result in the data and DOM being out of sync. In order to sort the array upon completion of the reorder, the array should be passed as a parameter to the `complete` method. The `complete` method will sort the array and return it so it can be reassigned.
+When the `complete` method is called on the reorder group with no parameters, the DOM nodes will be reordered. If the items are rendered from an array of data that needs to be sorted, this can result in the data and DOM being out of sync.
+
+In order to sort the array upon completion of the reorder, the array should be passed as a parameter to the `complete` method. The `complete` method will sort the array and return it so it can be reassigned. Note that passing the array will prevent Ionic from reordering the DOM nodes.
 
 In some cases, it may be necessary for an app to reorder both the array and the DOM nodes on its own. If this is required, `false` should be passed as a parameter to the `complete` method. This will prevent Ionic from reordering any DOM nodes inside of the reorder group.
 
+Regardless of the approach taken, a stable identity should be provided to reorder items if provided in a loop. This means using `trackBy` for Angular, and `key` for React and Vue.
+
 import UpdatingData from '@site/static/usage/v7/reorder/updating-data/index.md';
 
 <UpdatingData />

static/usage/v7/reorder/updating-data/angular/example_component_html.md

@@ -3,7 +3,7 @@
   <!-- 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-item *ngFor="let item of items">
+    <ion-item *ngFor="let item of items; trackBy: trackItems">
       <ion-label> Item {{ item }} </ion-label>
       <ion-reorder slot="end"></ion-reorder>
     </ion-item>

static/usage/v7/reorder/updating-data/angular/example_component_ts.md

@@ -23,5 +23,9 @@ export class ExampleComponent {
     // After complete is called the items will be in the new order
     console.log('After complete', this.items);
   }
+
+  trackItems(index: number, itemNumber: number) {
+    return itemNumber;
+  }
 }
 ```

static/usage/v7/reorder/updating-data/react.md

@@ -24,7 +24,7 @@ function Example() {
       {/* The reorder gesture is disabled by default, enable it to drag and drop items */}
       <IonReorderGroup disabled={false} onIonItemReorder={handleReorder}>
         {items.map((item) => (
-          <IonItem>
+          <IonItem key={item}>
             <IonLabel>Item {item}</IonLabel>
             <IonReorder slot="end"></IonReorder>
           </IonItem>

static/usage/v7/reorder/updating-data/vue.md

@@ -3,7 +3,7 @@
   <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-item v-for="item in items">
+      <ion-item v-for="item in items" :key="item">
         <ion-label> Item {{ item }} </ion-label>
         <ion-reorder slot="end"></ion-reorder>
       </ion-item>