@toolbox-web/grid 1.19.3 → 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

@@ -111,10 +111,10 @@ class In extends F {
     const t = e.clipboardData?.getData("text/plain");
     if (!t) return;
     e.preventDefault();
-    const i = _e(t, this.config), n = this.#s(), r = n?.ranges?.[0], o = r?.from.row ?? 0, s = r?.from.col ?? 0, d = r && (n?.mode === "range" || n?.mode === "row") && (r.from.row !== r.to.row || r.from.col !== r.to.col) ? { endRow: r.to.row, endCol: r.to.col } : null, c = d?.endCol ?? this.columns.length - 1, u = this.columns[s], h = u ? { row: o, col: s, field: u.field, bounds: d } : null, f = [], g = i[0]?.length ?? 0;
+    const i = _e(t, this.config), n = this.#s(), r = n?.ranges?.[0], o = r?.from.row ?? 0, s = r?.from.col ?? 0, d = r && (n?.mode === "range" || n?.mode === "row") && (r.from.row !== r.to.row || r.from.col !== r.to.col) ? { endRow: r.to.row, endCol: r.to.col } : null, c = d?.endCol ?? this.visibleColumns.length - 1, u = this.visibleColumns[s], h = u ? { row: o, col: s, field: u.field, bounds: d } : null, f = [], g = i[0]?.length ?? 0;
     for (let m = 0; m < g && s + m <= c; m++) {
-      const y = this.columns[s + m];
-      y && !y.hidden && f.push(y.field);
+      const y = this.visibleColumns[s + m];
+      y && f.push(y.field);
     }
     const p = { rows: i, text: t, target: h, fields: f };
     this.emit("paste", p), this.#o(p);
@@ -135,7 +135,7 @@ class In extends F {
       i = ie(this.columns, e.columns);
     else if (t?.ranges.length && t.mode !== "row") {
       const r = t.ranges[t.ranges.length - 1], o = Math.min(r.from.col, r.to.col), s = Math.max(r.from.col, r.to.col);
-      i = ie(this.columns.slice(o, s + 1));
+      i = ie(this.visibleColumns.slice(o, s + 1));
     } else
       i = ie(this.columns);
     let n;
@@ -3182,7 +3182,7 @@ class ut extends F {
   }
   onKeyDown(e) {
     if (e.key !== " ") return;
-    const t = this.grid._focusCol, i = this.grid._focusRow, n = this.columns[t];
+    const t = this.grid._focusCol, i = this.grid._focusRow, n = this.visibleColumns[t];
     if (!n || !se(n)) return;
     const r = this.rows[i];
     if (r)
@@ -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) {
@@ -5626,7 +5630,7 @@ class Bn extends F {
     if (!i) return !0;
     const n = this.rows[e];
     if (!n) return !1;
-    const r = t !== void 0 ? this.columns[t] : void 0;
+    const r = t !== void 0 ? this.visibleColumns[t] : void 0;
     return i(n, e, r, t);
   }
   isRowSelectable(e) {
@@ -5659,7 +5663,7 @@ class Bn extends F {
     const { rowIndex: t, colIndex: i, originalEvent: n } = e, { mode: r, triggerOn: o = "click" } = this.config;
     if (n.type !== o)
       return !1;
-    const s = this.columns[i], l = s && W(s);
+    const s = e.column, l = s && W(s);
     if (r === "cell") {
       if (l || !this.isCellSelectable(t, i))
         return !1;
@@ -5752,25 +5756,23 @@ class Bn extends F {
     return t === "range" && this.config.multiSelect !== !1 && e.key === "a" && (e.ctrlKey || e.metaKey) ? this.grid.query("isEditing").some(Boolean) ? !1 : (e.preventDefault(), e.stopPropagation(), this.selectAll(), !0) : !1;
   }
   onCellMouseDown(e) {
-    if (!this.isSelectionEnabled() || this.config.mode !== "range" || e.rowIndex === void 0 || e.colIndex === void 0 || e.rowIndex < 0) return;
-    const t = this.columns[e.colIndex];
-    if (t && W(t) || !this.isCellSelectable(e.rowIndex, e.colIndex) || e.originalEvent.shiftKey && this.cellAnchor)
+    if (!this.isSelectionEnabled() || this.config.mode !== "range" || e.rowIndex === void 0 || e.colIndex === void 0 || e.rowIndex < 0 || e.column && W(e.column) || !this.isCellSelectable(e.rowIndex, e.colIndex) || e.originalEvent.shiftKey && this.cellAnchor)
       return;
     this.isDragging = !0;
-    const i = e.rowIndex, n = e.colIndex, r = (e.originalEvent.ctrlKey || e.originalEvent.metaKey) && this.config.multiSelect !== !1, o = {
-      startRow: i,
-      startCol: n,
-      endRow: i,
-      endCol: n
+    const t = e.rowIndex, i = e.colIndex, n = (e.originalEvent.ctrlKey || e.originalEvent.metaKey) && this.config.multiSelect !== !1, r = {
+      startRow: t,
+      startCol: i,
+      endRow: t,
+      endCol: i
     };
-    return !r && this.ranges.length === 1 && ee(this.ranges[0], o) ? (this.cellAnchor = { row: i, col: n }, !0) : (this.cellAnchor = { row: i, col: n }, r || (this.ranges = []), this.ranges.push(o), this.activeRange = o, this.emit("selection-change", this.#i()), this.requestAfterRender(), !0);
+    return !n && this.ranges.length === 1 && ee(this.ranges[0], r) ? (this.cellAnchor = { row: t, col: i }, !0) : (this.cellAnchor = { row: t, col: i }, n || (this.ranges = []), this.ranges.push(r), this.activeRange = r, this.emit("selection-change", this.#i()), this.requestAfterRender(), !0);
   }
   onCellMouseMove(e) {
     if (!this.isSelectionEnabled() || this.config.mode !== "range" || !this.isDragging || !this.cellAnchor || e.rowIndex === void 0 || e.colIndex === void 0 || e.rowIndex < 0) return;
     let t = e.colIndex;
-    const i = this.columns[t];
+    const i = this.visibleColumns[t];
     if (i && W(i)) {
-      const o = this.columns.findIndex((s) => !W(s));
+      const o = this.visibleColumns.findIndex((s) => !W(s));
       o >= 0 && (t = o);
     }
     const n = ge(this.cellAnchor, { row: e.rowIndex, col: t }), r = this.ranges.length > 0 ? this.ranges[this.ranges.length - 1] : null;
@@ -5887,7 +5889,7 @@ class Bn extends F {
       e.querySelectorAll(".cell[data-row][data-col]").forEach((d) => {
         const c = parseInt(d.getAttribute("data-row") ?? "-1", 10), u = parseInt(d.getAttribute("data-col") ?? "-1", 10);
         if (c >= 0 && u >= 0) {
-          const h = this.columns[u];
+          const h = this.visibleColumns[u];
           if (h && W(h))
             return;
           s(c, u) && (d.classList.add("selected"), s(c - 1, u) || d.classList.add("top"), s(c + 1, u) || d.classList.add("bottom"), s(c, u - 1) || d.classList.add("first"), s(c, u + 1) || d.classList.add("last"));