docs(table): explain the importance of having ids

Author: Kiarokh

src/components/table/examples/table-remote.tsx

@@ -4,6 +4,7 @@ import { data, Bird } from './birds';
 import { capitalize } from 'lodash-es';
 
 const NETWORK_DELAY = 500;
+type BirdRow = Bird & { id: string };
 
 /**
  * Remote sorting and pagination
@@ -19,9 +20,9 @@ export class TableExampleRemote {
     private columns: Array<Column<Bird>> = [];
 
     @State()
-    private currentData: object[] = [];
+    private currentData: BirdRow[] = [];
 
-    private allData: object[] = data;
+    private allData: Bird[] = data;
 
     private pageSize = 10;
 
@@ -106,7 +107,15 @@ export class TableExampleRemote {
         setTimeout(() => {
             const start = (this.currentPage - 1) * this.pageSize;
             const end = start + this.pageSize;
-            this.currentData = this.allData.slice(start, end);
+
+            this.currentData = this.allData
+                .slice(start, end)
+                .map((item, index) => ({
+                    ...item,
+                    // Provide a stable id to keep scroll position and selection
+                    // intact while the remote dataset refreshes.
+                    id: `${item.binominalName}-${start + index}`,
+                }));
         }, NETWORK_DELAY);
     }
 

src/components/table/examples/table.tsx

@@ -3,6 +3,18 @@ import { Column } from '@limetech/lime-elements';
 import { Person, persons } from './persons';
 
 /**
+ * Basic example
+ *
+ * :::note
+ * Each object is recommended to expose a stable `id` (string or number).
+ * The table relies on that identifier to update rows in place so that
+ * scroll position, focus, and selections remain intact across renders.
+ *
+ * Rows without an `id` are treated as new data on every update.
+ * Therefore if the user clicks on a row at the bottom of the table,
+ * it will be treated as new data and will force a full redraw,
+ * resulting in the table to scroll to the top again.
+ * :::
  *
  * @sourceFile persons.ts
  */

src/components/table/table.tsx

@@ -51,7 +51,8 @@ const FIRST_PAGE = 1;
 })
 export class Table {
     /**
-     * Data to be displayed in the table
+     * Data to be displayed in the table. Provide a stable `id` on each row to keep
+     * scroll position, focus, and selections intact across updates.
      */
     @Prop()
     public data: object[] = [];