@toolbox-web/grid 1.20.0 → 1.21.0

package/README.md

@@ -252,13 +252,20 @@ The grid supports configuration via HTML attributes with JSON-serialized values:
 | `isCellLoading(rowId, field)`           | `boolean` | Check if cell is loading         |
 | `clearAllLoading()`                     | `void`    | Clear all loading states         |
 
+#### Row Mutation Methods
+
+| Method                            | Returns                   | Description                                        |
+| --------------------------------- | ------------------------- | -------------------------------------------------- |
+| `insertRow(index, row, animate?)` | `Promise<void>`           | Insert a row at a visible position (auto-animates) |
+| `removeRow(index, animate?)`      | `Promise<T \| undefined>` | Remove a row at a visible position (auto-animates) |
+
 #### Animation Methods
 
-| Method                       | Returns   | Description                                 |
-| ---------------------------- | --------- | ------------------------------------------- |
-| `animateRow(index, type)`    | `void`    | Animate a single row (change/insert/remove) |
-| `animateRows(indices, type)` | `void`    | Animate multiple rows at once               |
-| `animateRowById(id, type)`   | `boolean` | Animate row by ID (returns true if found)   |
+| Method                       | Returns            | Description                                 |
+| ---------------------------- | ------------------ | ------------------------------------------- |
+| `animateRow(index, type)`    | `Promise<boolean>` | Animate a single row (change/insert/remove) |
+| `animateRows(indices, type)` | `Promise<number>`  | Animate multiple rows at once               |
+| `animateRowById(id, type)`   | `Promise<boolean>` | Animate row by ID (resolves true if found)  |
 
 #### Plugin Methods
 
@@ -307,24 +314,43 @@ import { DGEvents } from '@toolbox-web/grid';
 grid.addEventListener(DGEvents.CELL_COMMIT, handler);
 ```
 
-### Row Animation API
+### Insert & Remove Rows
 
-Trigger visual feedback when rows change:
+Add or remove rows at a specific visible position without re-running the sort/filter pipeline:
 
 ```typescript
-// Flash highlight for updated row
-grid.animateRow(5, 'change');
+// Insert with animation (default)
+grid.insertRow(3, newEmployee);
 
-// Slide-in for new row
-grid.animateRow(0, 'insert');
+// Insert without animation
+grid.insertRow(3, newEmployee, false);
 
-// Fade-out for removed row
-grid.animateRow(3, 'remove');
+// Remove with fade-out animation and await completion
+await grid.removeRow(5);
+
+// Remove without animation
+const removed = await grid.removeRow(5, false);
+```
+
+Both methods update the source data automatically. The next full `grid.rows = freshData` assignment re-sorts/re-filters normally. Do **not** use them for bulk data refreshes — assign `grid.rows` directly instead.
+
+### Row Animation API
+
+All animation methods return **Promises** that resolve when the animation completes:
+
+```typescript
+// Flash highlight for updated row
+await grid.animateRow(5, 'change');
 
 // Animate by row ID
-grid.animateRowById('emp-123', 'change');
+await grid.animateRowById('emp-123', 'change');
+
+// Animate multiple rows
+await grid.animateRows([0, 1, 2], 'change');
 ```
 
+> **Note:** `insertRow` and `removeRow` handle animation automatically — you only need `animateRow` directly for highlighting existing rows (e.g., after an external data update).
+
 **Animation Types:** `'change'` | `'insert'` | `'remove'`
 
 ### Animation Configuration

package/all.js

@@ -3364,6 +3364,10 @@ class qn extends F {
   }
   sortModel = [];
   cachedSortResult = null;
+  clearCoreSortState() {
+    const e = this.gridElement;
+    e && (e._sortState = null);
+  }
   detach() {
     this.sortModel = [], this.cachedSortResult = null;
   }
@@ -3379,7 +3383,7 @@ class qn extends F {
   onHeaderClick(e) {
     if (!this.columns.find((r) => r.field === e.field)?.sortable) return !1;
     const i = e.originalEvent.shiftKey, n = this.config.maxSortColumns ?? 3;
-    return this.sortModel = Ci(this.sortModel, e.field, i, n), this.emit("sort-change", { sortModel: [...this.sortModel] }), this.requestRender(), this.grid?.requestStateChange?.(), !0;
+    return this.sortModel = Ci(this.sortModel, e.field, i, n), this.clearCoreSortState(), this.emit("sort-change", { sortModel: [...this.sortModel] }), this.requestRender(), this.grid?.requestStateChange?.(), !0;
   }
   afterRender() {
     const e = this.gridElement;
@@ -3406,10 +3410,10 @@ class qn extends F {
     return [...this.sortModel];
   }
   setSortModel(e) {
-    this.sortModel = [...e], this.emit("sort-change", { sortModel: [...e] }), this.requestRender(), this.grid?.requestStateChange?.();
+    this.sortModel = [...e], this.clearCoreSortState(), this.emit("sort-change", { sortModel: [...e] }), this.requestRender(), this.grid?.requestStateChange?.();
   }
   clearSort() {
-    this.sortModel = [], this.emit("sort-change", { sortModel: [] }), this.requestRender(), this.grid?.requestStateChange?.();
+    this.sortModel = [], this.clearCoreSortState(), this.emit("sort-change", { sortModel: [] }), this.requestRender(), this.grid?.requestStateChange?.();
   }
   getSortIndex(e) {
     return Be(this.sortModel, e);
@@ -3435,7 +3439,7 @@ class qn extends F {
       field: e,
       direction: t.sort.direction
     };
-    i !== -1 ? this.sortModel[i] = n : this.sortModel.splice(t.sort.priority, 0, n);
+    i !== -1 ? this.sortModel[i] = n : this.sortModel.splice(t.sort.priority, 0, n), this.clearCoreSortState();
   }
 }
 function O(a) {