@iyulab/flex-table 0.55.2 → 0.56.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.56.0] - 2026-10-07
+
+### Fixed
+
+- **Row selection stays on its rows.** The checkmarks were kept by screen position, so sorting, filtering, inserting
+  or deleting rows moved them onto other rows without a `selection-change` — select a row, sort, and a different row
+  was selected (and a bulk action took it). Replacing `data` with other rows of the same length carried the
+  checkmarks onto the new rows. Selection is now kept by row id (see `rowKey` below).
+- **`deleteRows()` without indices deletes the checked rows in a `selectable` grid.** It deleted the rows of the
+  cell selection (the active cell's row), so a «Delete selected» button removed a row nobody checked. With nothing
+  checked it now deletes nothing. A grid without checkboxes keeps deleting the cell selection's rows.
+
+### Added
+
+- **`rowKey`** (`row-key`, default `'_id'` — the field `u-rich-table` reads) — the field, or a function of the row,
+  that names a row. A keyed row stays selected when `data` is replaced, so a selection spans server pages. A row
+  without a key is named by the row object (a session-local id `#n`) and leaves the selection when `data` no longer
+  holds it.
+- `getRowId(row)`, the `selectedRowIds` getter and `setSelection(ids)` (does nothing, and fires nothing, when the
+  selection already is `ids`).
+- `selection-change` carries `selectedIds` — every selected row, on every page — next to `selectedRows` and
+  `selectedIndices` (the selected rows `data` holds). `row-activate` carries the row's `id`.
+
+### Changed (breaking)
+
+- The header checkbox and `selectAll()` act on the rows in view: rows selected on another page stay selected, and
+  unchecking the header deselects only the rows in view. `deselectAll()` still clears every page. A selected row a
+  filter hides stays selected (and in `selectedRows`).
+- `RowSelectionState` (exported) keeps ids: `isSelected(id)`, `toggle(id)`, `select(id)`, `selectAll(ids)`,
+  `deselectMany(ids)`, `set(ids)`, `retain(keep)`, `selectRange(orderedIds, from, to)`, `isAllSelected(ids)`,
+  `isSomeSelected(ids)`, `selectedIds`. `setRowCount` and `selectedIndices` are gone.
+- `clear-selection-on-data-change` keeps its meaning; it is no longer needed to stop a replacement from moving the
+  checkmarks.
+
+**Migrating**: give rows a stable key (`_id`, or set `rowKey`) when selection should survive a reload or a page change.
+Read `selectedIds` for «what is selected» across pages, `selectedRows` for the rows on hand. A «Delete selected» button
+on a `selectable` grid can keep calling `deleteRows()`.
+
 ## [0.55.2] - 2026-10-07
 
 ### Documentation

package/README.md

@@ -108,6 +108,7 @@ guarantee about a *constrained* host. `height-model.browser.test.ts` pins both s
 | `maxRows` | `max-rows` | `number` | `0` | Max row count (0 = unlimited); blocks `addRow()` and paste expansion |
 | `maxUndoSize` | `max-undo-size` | `number` | `100` | Max undo history stack size |
 | `selectable` | `selectable` | `boolean` | `false` | Enable row-level checkbox selection |
+| `rowKey` | `row-key` | `string \| (row) => unknown` | `'_id'` | What names a row — selection is kept by this id (see [Row Selection](#row-selection)) |
 | `selectionMode` | `selection-mode` | `'single' \| 'multi'` | `'multi'` | Row selection mode |
 | `dataMode` | `data-mode` | `'client' \| 'server'` | `'client'` | Client-side or server-side data processing |
 | `footerData` | `footer-data` | `Record<string, string \| TemplateResult> \| null` | `null` | Footer/summary row data (keys match column keys) |
@@ -235,7 +236,7 @@ Every row keeps its own value. Sorting, filtering, copying, CSV/XLSX export and
 | Method | Returns | Description |
 |--------|---------|-------------|
 | `addRow(row?, index?)` | `DataRow \| null` | Add a row. Returns `null` if `maxRows` reached |
-| `deleteRows(indices?)` | `void` | Delete rows by data index (default: selected rows) |
+| `deleteRows(indices?)` | `void` | Delete rows by data index. Without indices: the checked rows when `selectable` (none checked — nothing), otherwise the rows of the cell selection |
 | `updateRows(changes)` | `void` | Batch update cells as single undo action. `changes: Array<{ row, key, value }>` |
 | `refreshData()` | `void` | Force re-render after in-place data mutation |
 
@@ -253,11 +254,21 @@ Every row keeps its own value. Sorting, filtering, copying, CSV/XLSX export and
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `selectAll()` | `void` | Select all visible rows (multi mode only) |
-| `deselectAll()` | `void` | Deselect all rows |
-| `getSelectedRows()` | `{ selectedIndices, selectedRows }` | Get selected row data |
+| `selectAll()` | `void` | Select every row in view, after filtering (multi mode only). Rows on other pages stay as they are |
+| `deselectAll()` | `void` | Deselect every row, on every page |
+| `selectWhere(predicate)` | `void` | Add the rows in view for which `predicate(row, dataIndex)` is true |
+| `setSelection(ids)` | `void` | Replace the selection with these row ids. The same set again does nothing and fires nothing |
+| `getSelectedRows()` | `{ selectedIds, selectedIndices, selectedRows }` | `selectedIds`: every selected row (all pages). `selectedRows` / `selectedIndices`: the selected rows `data` holds, and their positions in it |
+| `getRowId(row)` | `string` | The id selection keeps for a row |
+| `selectedRowIds` (getter) | `ReadonlySet<string>` | Ids of the selected rows, all pages (a copy) |
 
-Row selection is index-based (there is no row-key concept), so replacing `data` with a same-length but different set of rows leaves the selection pointing at the new rows occupying the old indices. If selection drives a bulk action (status changes, bulk delete, etc.), set `clear-selection-on-data-change` so a `data` swap always resets selection and re-fires `selection-change` with an empty selection:
+Row selection is kept by **row id**, not by position, so a checkmark stays on its row through sorting, filtering, inserts and deletes. The id is the row's `row-key` field — `_id` by default, the same field `u-rich-table` reads — or the result of a `rowKey` function:
+
+```ts
+table.rowKey = 'orderNo';                       // or: table.rowKey = (row) => `${row.site}/${row.no}`
+```
+
+A keyed row stays selected when `data` is replaced, so in a server-paged grid the selection spans pages (`selectedIds` names them all; `selectedRows` holds the ones on this page). A row without a key is named by the row object itself (a session-local id `#n`): it follows the row while the same object is in `data` and leaves the selection when it is gone. Set `clear-selection-on-data-change` when every new `data` should start a new selection (a new search):
 
 ```html
 <flex-table selectable clear-selection-on-data-change></flex-table>
@@ -304,7 +315,7 @@ type-checks without a cast. The React wrapper's `on*` props carry the same types
 |-------|--------|-------------|
 | `row-add` | `{ row, index }` | Row added |
 | `row-delete` | `{ indices, rows }` | Rows deleted |
-| `row-activate` | `{ row, index, col, key }` | Enter pressed on a non-editable cell — the grid's own contract for "activate this row" (e.g. navigate to a detail view), guaranteed even though the internal Enter handler prevents the keystroke from reliably reaching a listener the host attaches to the same element |
+| `row-activate` | `{ row, id, index, col, key }` | Enter pressed on a non-editable cell — the grid's own contract for "activate this row" (e.g. navigate to a detail view), guaranteed even though the internal Enter handler prevents the keystroke from reliably reaching a listener the host attaches to the same element |
 | `batch-update` | `{ changes: [{ row, key, oldValue, newValue }] }` | Batch update applied |
 | `row-reorder` | `{ from, to }` | Row dragged to a new place (data indices) |
 | `data-import` | `{ count }` | Rows imported from a file |
@@ -336,7 +347,7 @@ type-checks without a cast. The React wrapper's `on*` props carry the same types
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `selection-change` | `{ selectedIndices, selectedRows }` | Row checkbox selection changed |
+| `selection-change` | `{ selectedIds, selectedIndices, selectedRows }` | Row checkbox selection changed — `selectedIds` covers every page, `selectedRows` the rows `data` holds |
 
 ### Clipboard Events
 

package/dist/core/row-selection.d.ts

@@ -1,30 +1,41 @@
 import type { SelectionMode } from '../models/types.js';
 /**
- * Manages row-level selection state (checkbox-based).
- * Separate from cell-level SelectionState.
+ * Row-level (checkbox) selection, kept as a set of row ids — see `FlexTable.getRowId`.
+ * Separate from the cell-level `SelectionState`.
+ *
+ * An id names a row, not a position: sorting, filtering, inserting or deleting rows leaves the checkmarks on the
+ * rows they were put on. The header checkbox and "select all" act on the rows currently in view (`ids` arguments);
+ * ids of rows that are not in view (another server page) stay selected.
  */
 export declare class RowSelectionState {
     private _selected;
     private _mode;
-    private _rowCount;
     get mode(): SelectionMode;
     set mode(value: SelectionMode);
-    setRowCount(count: number): void;
-    get selectedIndices(): number[];
+    /** Selected ids, in the order they were selected. */
+    get selectedIds(): string[];
     get selectedCount(): number;
-    get isAllSelected(): boolean;
-    get isSomeSelected(): boolean;
-    isSelected(index: number): boolean;
-    toggle(index: number): void;
-    select(index: number): void;
-    deselect(index: number): void;
-    selectAll(): void;
+    isSelected(id: string): boolean;
+    /** Every one of `ids` (the rows in view) is selected — false when `ids` is empty. */
+    isAllSelected(ids: readonly string[]): boolean;
+    /** Some but not all of `ids` (the rows in view) are selected. */
+    isSomeSelected(ids: readonly string[]): boolean;
+    toggle(id: string): void;
+    select(id: string): void;
+    deselect(id: string): void;
+    /** Adds `ids` to the selection (multi mode only — one slot cannot hold a set). */
+    selectAll(ids: readonly string[]): void;
+    /** Removes `ids` from the selection — the rest stays. */
+    deselectMany(ids: readonly string[]): void;
     deselectAll(): void;
+    /** Replaces the selection with `ids` (single mode keeps the last). Returns whether it changed. */
+    set(ids: Iterable<string>): boolean;
+    /** Keeps only the ids `keep` accepts. Returns whether anything was dropped. */
+    retain(keep: (id: string) => boolean): boolean;
     /**
-     * Selects every index between from and to, inclusive, in either direction.
-     * Used for shift-click range selection anchored at the last toggled row.
-     * Single mode: only the endpoint (to) ends up selected, matching toggle()'s
-     * "one at a time" semantics — a range doesn't make sense with one slot.
+     * Selects `ids` between the positions of `from` and `to` in `ordered` (the rows in view, top to bottom), inclusive,
+     * in either direction — shift-click range selection anchored at the last toggled row. Single mode selects only
+     * `to`, matching `toggle()`'s one-slot semantics. An anchor that is no longer in view selects only `to`.
      */
-    selectRange(from: number, to: number): void;
+    selectRange(ordered: readonly string[], from: string, to: string): void;
 }

package/dist/events.d.ts

@@ -19,7 +19,9 @@ export interface CellChange {
  */
 export interface FlexTableEventMap {
     /** Row selection changed (`selectable`). Indices are data indices. */
+    /** `selectedIds` — every selected row (all pages, see `rowKey`); `selectedRows`/`selectedIndices` — the selected rows `data` holds. */
     'selection-change': CustomEvent<{
+        selectedIds: string[];
         selectedIndices: number[];
         selectedRows: DataRow[];
     }>;
@@ -83,8 +85,10 @@ export interface FlexTableEventMap {
         to: number;
     }>;
     /** Enter on a non-editable cell — "activate this row". `index` is the data index, `col` the visible column index. */
+    /** `id` — the row's id (`getRowId`); `index` — its position in `data`; `key` — the active column's key. */
     'row-activate': CustomEvent<{
         row: DataRow;
+        id: string;
         index: number;
         col: number;
         key: string | undefined;

package/dist/{flex-table-D3E9npd9.js → flex-table-M_oC8OXD.js}

@@ -1225,7 +1225,7 @@ var oe = class {
 	}
 }, k = class {
 	constructor() {
-		this._selected = /* @__PURE__ */ new Set(), this._mode = "multi", this._rowCount = 0;
+		this._selected = /* @__PURE__ */ new Set(), this._mode = "multi";
 	}
 	get mode() {
 		return this._mode;
@@ -1236,27 +1236,24 @@ var oe = class {
 			this._selected.clear(), e !== void 0 && this._selected.add(e);
 		}
 	}
-	setRowCount(e) {
-		this._rowCount = e;
-		for (let t of this._selected) t >= e && this._selected.delete(t);
-	}
-	get selectedIndices() {
-		return [...this._selected].sort((e, t) => e - t);
+	get selectedIds() {
+		return [...this._selected];
 	}
 	get selectedCount() {
 		return this._selected.size;
 	}
-	get isAllSelected() {
-		return this._rowCount > 0 && this._selected.size === this._rowCount;
-	}
-	get isSomeSelected() {
-		return this._selected.size > 0 && this._selected.size < this._rowCount;
-	}
 	isSelected(e) {
 		return this._selected.has(e);
 	}
+	isAllSelected(e) {
+		return e.length > 0 && e.every((e) => this._selected.has(e));
+	}
+	isSomeSelected(e) {
+		let t = e.reduce((e, t) => e + +!!this._selected.has(t), 0);
+		return t > 0 && t < e.length;
+	}
 	toggle(e) {
-		this._mode === "single" ? this._selected.has(e) ? this._selected.clear() : (this._selected.clear(), this._selected.add(e)) : this._selected.has(e) ? this._selected.delete(e) : this._selected.add(e);
+		this._selected.has(e) ? this._selected.delete(e) : this.select(e);
 	}
 	select(e) {
 		this._mode === "single" && this._selected.clear(), this._selected.add(e);
@@ -1264,22 +1261,31 @@ var oe = class {
 	deselect(e) {
 		this._selected.delete(e);
 	}
-	selectAll() {
-		if (this._mode !== "single") {
-			this._selected.clear();
-			for (let e = 0; e < this._rowCount; e++) this._selected.add(e);
-		}
+	selectAll(e) {
+		if (this._mode !== "single") for (let t of e) this._selected.add(t);
+	}
+	deselectMany(e) {
+		for (let t of e) this._selected.delete(t);
 	}
 	deselectAll() {
 		this._selected.clear();
 	}
-	selectRange(e, t) {
-		if (this._mode === "single") {
-			this.select(t);
+	set(e) {
+		let t = [...new Set(e)], n = this._mode === "single" ? t.slice(-1) : t;
+		return n.length === this._selected.size && n.every((e) => this._selected.has(e)) ? !1 : (this._selected = new Set(n), !0);
+	}
+	retain(e) {
+		let t = !1;
+		for (let n of this._selected) e(n) || (this._selected.delete(n), t = !0);
+		return t;
+	}
+	selectRange(e, t, n) {
+		let r = e.indexOf(t), i = e.indexOf(n);
+		if (this._mode === "single" || r < 0 || i < 0) {
+			this.select(n);
 			return;
 		}
-		let n = Math.min(e, t), r = Math.max(e, t);
-		for (let e = n; e <= r; e++) e >= 0 && e < this._rowCount && this._selected.add(e);
+		for (let t = Math.min(r, i); t <= Math.max(r, i); t++) this._selected.add(e[t]);
 	}
 };
 //#endregion
@@ -1756,7 +1762,7 @@ var K = {
 	lte: "≤"
 }, q = 120, J = 40, Y = 20, X = 32, Z = 5, Xe = 200, Q = class extends r {
 	constructor(...e) {
-		super(...e), this.columns = [], this._data = [], this._inUndoRedo = !1, this.clearUndoOnDataChange = !1, this.clearSelectionOnDataChange = !1, this._rowHeightFromCss = X, this._targetFloor = 0, this.showRowNumbers = !1, this.theme = void 0, this.maxRows = 0, this.editable = !0, this.showFilters = !1, this.showContextMenu = !1, this.frozenRows = 0, this.emptyMessage = "", this.noMatchingMessage = "", this.error = null, this.loading = !1, this.importEnabled = !1, this.selectable = !1, this.dataMode = "client", this.footerData = null, this.stylesheets = [], this._scrollTop = 0, this._scrollLeft = 0, this._viewportHeight = 0, this._viewportWidth = 0, this._colLeftOffsets = [], this._totalRowWidth = 0, this._baseStyleSheets = [], this._activeCell = null, this._headerCol = null, this._focusedCellEl = null, this._editingCell = null, this._sortCriteria = [], this._selection = new oe(), this._editing = new se(), this._rowSelection = new k(), this._undo = new A(), this._filters = [], this._filteredIndices = [], this._sortedIndices = [], this._openFilterKey = null, this._rowSelectionVersion = 0, this._lastCheckboxRowIndex = null, this._checkboxShiftPending = !1, this._autocompleteState = null, this._headerMenu = null, this._bodyContextMenu = null, this._commentPopup = null, this._viewDirty = !0, this._isDragging = !1, this._wasDrag = !1, this._resizing = null, this._resizeCleanup = null, this._wasHeaderDrag = !1, this._wasRowDrag = !1, this._colDrag = null, this._colDragIndicatorLeft = null, this._fillDrag = null, this._rowDrag = null, this._rowDragIndicatorY = null, this._findState = null, this._columnWidths = /* @__PURE__ */ new Map(), this._hostResizeObserver = null, this._comments = /* @__PURE__ */ new Map(), this._isDragOver = !1, this._warnedUnconstrained = !1, this._onHostFocus = (e) => {
+		super(...e), this.columns = [], this._data = [], this._inUndoRedo = !1, this.clearUndoOnDataChange = !1, this.clearSelectionOnDataChange = !1, this.rowKey = "_id", this._rowHeightFromCss = X, this._targetFloor = 0, this.showRowNumbers = !1, this.theme = void 0, this.maxRows = 0, this.editable = !0, this.showFilters = !1, this.showContextMenu = !1, this.frozenRows = 0, this.emptyMessage = "", this.noMatchingMessage = "", this.error = null, this.loading = !1, this.importEnabled = !1, this.selectable = !1, this.dataMode = "client", this.footerData = null, this.stylesheets = [], this._scrollTop = 0, this._scrollLeft = 0, this._viewportHeight = 0, this._viewportWidth = 0, this._colLeftOffsets = [], this._totalRowWidth = 0, this._baseStyleSheets = [], this._activeCell = null, this._headerCol = null, this._focusedCellEl = null, this._editingCell = null, this._sortCriteria = [], this._selection = new oe(), this._editing = new se(), this._rowSelection = new k(), this._undo = new A(), this._filters = [], this._filteredIndices = [], this._sortedIndices = [], this._openFilterKey = null, this._rowSelectionVersion = 0, this._lastCheckboxRowId = null, this._unkeyedIds = /* @__PURE__ */ new WeakMap(), this._unkeyedSeq = 0, this._visibleIdsCache = null, this._checkboxShiftPending = !1, this._autocompleteState = null, this._headerMenu = null, this._bodyContextMenu = null, this._commentPopup = null, this._viewDirty = !0, this._isDragging = !1, this._wasDrag = !1, this._resizing = null, this._resizeCleanup = null, this._wasHeaderDrag = !1, this._wasRowDrag = !1, this._colDrag = null, this._colDragIndicatorLeft = null, this._fillDrag = null, this._rowDrag = null, this._rowDragIndicatorY = null, this._findState = null, this._columnWidths = /* @__PURE__ */ new Map(), this._hostResizeObserver = null, this._comments = /* @__PURE__ */ new Map(), this._isDragOver = !1, this._warnedUnconstrained = !1, this._onHostFocus = (e) => {
 			e.composedPath()[0] !== this || this._activeCell || this._headerCol !== null || this.visibleColumns.length !== 0 && this.matches(":focus-visible") && (this._visibleRowCount > 0 ? (this._selection.setActive(0, 0), this._syncActiveCell()) : this._headerCol = 0);
 		}, this._onFocusIn = (e) => {
 			let t = e.composedPath()[0];
@@ -1784,7 +1790,7 @@ var K = {
 	}
 	set data(e) {
 		let t = this._data, n = e !== t;
-		this._data = e, n && !this._inUndoRedo && (this.clearUndoOnDataChange && this._undo.clear(), this.clearSelectionOnDataChange && this._rowSelection.selectedCount > 0 && (this._rowSelection.deselectAll(), this._rowSelectionVersion++, this._dispatchRowSelectionEvent())), this.requestUpdate("data", t);
+		this._data = e, n && !this._inUndoRedo && (this.clearUndoOnDataChange && this._undo.clear(), this._rowSelection.selectedCount > 0 && (this.clearSelectionOnDataChange ? (this._rowSelection.deselectAll(), 1) : this._pruneGoneUnkeyedRows()) && (this._rowSelectionVersion++, this._dispatchRowSelectionEvent())), this.requestUpdate("data", t);
 	}
 	get rowHeight() {
 		let e = this._rowHeightExplicit ?? this._rowHeightFromCss ?? X;
@@ -1835,14 +1841,28 @@ var K = {
 		return this._filteredIndices.length;
 	}
 	getSelectedRows() {
-		let e = this._rowSelection.selectedIndices.map((e) => this._toDataIndex(e)).filter((e) => e >= 0 && e < this.data.length);
+		let e = [];
+		if (this._rowSelection.selectedCount > 0) for (let t = 0; t < this.data.length; t++) this._rowSelection.isSelected(this.getRowId(this.data[t])) && e.push(t);
 		return {
+			selectedIds: this._rowSelection.selectedIds,
 			selectedIndices: e,
 			selectedRows: e.map((e) => this.data[e])
 		};
 	}
+	getRowId(e) {
+		let t = this.rowKey, n = typeof t == "function" ? t(e) : e[t];
+		if (n != null && n !== "") return String(n);
+		let r = this._unkeyedIds.get(e);
+		return r === void 0 && (r = `#${++this._unkeyedSeq}`, this._unkeyedIds.set(e, r)), r;
+	}
+	get selectedRowIds() {
+		return new Set(this._rowSelection.selectedIds);
+	}
+	setSelection(e) {
+		this.selectable && this._rowSelection.set(e) && (this._rowSelectionVersion++, this._dispatchRowSelectionEvent(), this.requestUpdate());
+	}
 	selectAll() {
-		this.selectable && (this._rowSelection.selectAll(), this._rowSelectionVersion++, this._dispatchRowSelectionEvent());
+		this.selectable && (this._rowSelection.selectAll(this._visibleRowIds()), this._rowSelectionVersion++, this._dispatchRowSelectionEvent());
 	}
 	deselectAll() {
 		this.selectable && (this._rowSelection.deselectAll(), this._rowSelectionVersion++, this._dispatchRowSelectionEvent());
@@ -1851,17 +1871,33 @@ var K = {
 		if (this.selectable) {
 			for (let t = 0; t < this._visibleRowCount; t++) {
 				let n = this._toDataIndex(t), r = this.data[n];
-				r !== void 0 && e(r, n) && this._rowSelection.select(t);
+				r !== void 0 && e(r, n) && this._rowSelection.select(this.getRowId(r));
 			}
 			this._rowSelectionVersion++, this._dispatchRowSelectionEvent(), this.requestUpdate();
 		}
 	}
 	_dispatchRowSelectionEvent() {
-		let { selectedIndices: e, selectedRows: t } = this.getSelectedRows();
-		this._emit("selection-change", {
-			selectedIndices: e,
-			selectedRows: t
-		});
+		this._emit("selection-change", this.getSelectedRows());
+	}
+	_visibleRowIds() {
+		let e = this._visibleIdsCache;
+		if (e && e.order === this._sortedIndices && e.data === this.data && e.key === this.rowKey && e.ids.length === this._visibleRowCount) return e.ids;
+		let t = [];
+		for (let e = 0; e < this._visibleRowCount; e++) {
+			let n = this.data[this._toDataIndex(e)];
+			n !== void 0 && t.push(this.getRowId(n));
+		}
+		return this._visibleIdsCache = {
+			order: this._sortedIndices,
+			data: this.data,
+			key: this.rowKey,
+			ids: t
+		}, t;
+	}
+	_pruneGoneUnkeyedRows() {
+		if (!this._rowSelection.selectedIds.some((e) => e.startsWith("#"))) return !1;
+		let e = new Set(this.data.map((e) => this.getRowId(e)));
+		return this._rowSelection.retain((t) => !t.startsWith("#") || e.has(t));
 	}
 	setFilter(e, t) {
 		this._filters = this._filters.filter((t) => t.key !== e), this._filters.push({
@@ -2037,34 +2073,35 @@ var K = {
 		}), this._dispatchUndoStateEvent(), n;
 	}
 	deleteRows(e) {
-		let t = e ?? this._getSelectedDataRows();
+		let t = e ?? (this.selectable ? this.getSelectedRows().selectedIndices : this._getSelectedDataRows());
 		if (t.length === 0) return;
 		let n = [...t].sort((e, t) => t - e), r = [];
 		for (let e of n) e >= 0 && e < this.data.length && (r.push({
 			index: e,
 			row: this.data[e]
 		}), this.data.splice(e, 1));
-		if (r.length !== 0) {
-			if (r.reverse(), this._undo.push({
-				label: "row-delete",
-				undo: () => {
-					for (let { index: e, row: t } of r) this.data.splice(e, 0, t);
-					this.requestUpdate();
-				},
-				redo: () => {
-					let e = [...r].reverse();
-					for (let { index: t } of e) this.data.splice(t, 1);
-					this.requestUpdate();
-				}
-			}), this._activeCell) {
-				let e = this._toDataIndex(this._activeCell.row);
-				t.includes(e) && (this._selection.clear(), this._activeCell = null);
+		if (r.length === 0) return;
+		r.reverse(), this._undo.push({
+			label: "row-delete",
+			undo: () => {
+				for (let { index: e, row: t } of r) this.data.splice(e, 0, t);
+				this.requestUpdate();
+			},
+			redo: () => {
+				let e = [...r].reverse();
+				for (let { index: t } of e) this.data.splice(t, 1);
+				this.requestUpdate();
 			}
-			this.requestUpdate(), this._emit("row-delete", {
-				indices: r.map((e) => e.index),
-				rows: r.map((e) => e.row)
-			}), this._dispatchUndoStateEvent();
+		});
+		let i = r.map((e) => this.getRowId(e.row)).filter((e) => this._rowSelection.isSelected(e));
+		if (i.length > 0 && (this._rowSelection.deselectMany(i), this._rowSelectionVersion++, this._dispatchRowSelectionEvent()), this._activeCell) {
+			let e = this._toDataIndex(this._activeCell.row);
+			t.includes(e) && (this._selection.clear(), this._activeCell = null);
 		}
+		this.requestUpdate(), this._emit("row-delete", {
+			indices: r.map((e) => e.index),
+			rows: r.map((e) => e.row)
+		}), this._dispatchUndoStateEvent();
 	}
 	updateRows(e) {
 		if (e.length === 0) return;
@@ -2354,7 +2391,7 @@ var K = {
 		};
 	}
 	willUpdate(e) {
-		(!(e.size <= 2 && !e.has("data") && !e.has("columns") && !e.has("_openFilterKey") && !e.has("_editingCell") && !e.has("_activeCell") && (e.has("_scrollTop") || e.has("_scrollLeft"))) || this._viewDirty) && (this._recomputeView(), this._viewDirty = !1), this._updateColOffsets(), this._selection.setDimensions(this._visibleRowCount, this.visibleColumns.length), this._rowSelection.setRowCount(this._visibleRowCount);
+		(!(e.size <= 2 && !e.has("data") && !e.has("columns") && !e.has("_openFilterKey") && !e.has("_editingCell") && !e.has("_activeCell") && (e.has("_scrollTop") || e.has("_scrollLeft"))) || this._viewDirty) && (this._recomputeView(), this._viewDirty = !1), this._updateColOffsets(), this._selection.setDimensions(this._visibleRowCount, this.visibleColumns.length);
 	}
 	updated(e) {
 		this._focusEditor(), this._syncGridFocus(), this._adjustFilterDropdown(), e.has("_headerMenu") && this._keepMenuInView(".ft-header-menu"), e.has("_bodyContextMenu") && this._bodyContextMenu && (this._keepMenuInView(".ft-body-context-menu"), this.shadowRoot?.querySelector(".ft-body-context-menu [role=\"menuitem\"]")?.focus()), e.has("stylesheets") && this._syncStylesheets();
@@ -2492,6 +2529,7 @@ var K = {
 		let t = this._toDataIndex(this._activeCell.row), n = this.data[t];
 		n && this._emit("row-activate", {
 			row: n,
+			id: this.getRowId(n),
 			index: t,
 			col: this._activeCell.col,
 			key: e?.key
@@ -2722,7 +2760,11 @@ var K = {
 			}
 			if (!this._handleCtrlKey(e) && !this._handleAltKey(e, t)) {
 				if (e.key === " " && e.shiftKey && this.selectable && this._activeCell && !e.ctrlKey && !e.metaKey && !e.altKey) {
-					e.preventDefault(), this._rowSelection.toggle(this._activeCell.row), this._lastCheckboxRowIndex = this._activeCell.row, this._rowSelectionVersion++, this._dispatchRowSelectionEvent();
+					e.preventDefault();
+					let t = this.data[this._toDataIndex(this._activeCell.row)];
+					if (!t) return;
+					let n = this.getRowId(t);
+					this._rowSelection.toggle(n), this._lastCheckboxRowId = n, this._rowSelectionVersion++, this._dispatchRowSelectionEvent();
 					return;
 				}
 				if (this._activeCell && e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
@@ -4146,8 +4188,8 @@ var K = {
           ${this._rowSelection.mode === "multi" ? a`
             <!-- 칸 전체가 누르는 자리다(라벨) — 체크 상자는 16px 그대로. -->
             <label class="ft-checkbox-hit"><input type="checkbox" tabindex="-1" aria-label=${e("selectAllRows")}
-              .checked=${this._rowSelection.isAllSelected}
-              .indeterminate=${this._rowSelection.isSomeSelected}
+              .checked=${this._rowSelection.isAllSelected(this._visibleRowIds())}
+              .indeterminate=${this._rowSelection.isSomeSelected(this._visibleRowIds())}
               @change=${this._onSelectAllChange}></label>
           ` : ""}
         </div>` : "";
@@ -4194,10 +4236,14 @@ var K = {
     `;
 	}
 	_onSelectAllChange(e) {
-		e.target.checked ? this._rowSelection.selectAll() : this._rowSelection.deselectAll(), this._rowSelectionVersion++, this._dispatchRowSelectionEvent();
+		e.target.checked ? this._rowSelection.selectAll(this._visibleRowIds()) : this._rowSelection.deselectMany(this._visibleRowIds()), this._rowSelectionVersion++, this._dispatchRowSelectionEvent();
 	}
 	_onRowCheckboxChange(e, t) {
-		e.stopPropagation(), this._checkboxShiftPending && this._lastCheckboxRowIndex !== null ? this._rowSelection.selectRange(this._lastCheckboxRowIndex, t) : this._rowSelection.toggle(t), this._lastCheckboxRowIndex = t, this._checkboxShiftPending = !1, this._rowSelectionVersion++, this._dispatchRowSelectionEvent();
+		e.stopPropagation();
+		let n = this.data[this._toDataIndex(t)];
+		if (!n) return;
+		let r = this.getRowId(n);
+		this._checkboxShiftPending && this._lastCheckboxRowId !== null ? this._rowSelection.selectRange(this._visibleRowIds(), this._lastCheckboxRowId, r) : this._rowSelection.toggle(r), this._lastCheckboxRowId = r, this._checkboxShiftPending = !1, this._rowSelectionVersion++, this._dispatchRowSelectionEvent();
 	}
 	_onRowCheckboxClick(e) {
 		this._checkboxShiftPending = e.shiftKey;
@@ -4242,7 +4288,7 @@ var K = {
     `;
 	}
 	_renderRow(t, n, r, i, o) {
-		let s = this.visibleColumns, c = this._toDataIndex(t), l = this.data[c], u = o ?? t * this.rowHeight, d = this.rowHeight, f = this._totalRowWidth, p = t % 2 == 0 ? "ft-row-even" : "ft-row-odd", m = this.selectable && this._rowSelection.isSelected(t), h = this._scrollLeft, g = 0, _ = this.selectable ? a`
+		let s = this.visibleColumns, c = this._toDataIndex(t), l = this.data[c], u = o ?? t * this.rowHeight, d = this.rowHeight, f = this._totalRowWidth, p = t % 2 == 0 ? "ft-row-even" : "ft-row-odd", m = this.selectable && l !== void 0 && this._rowSelection.isSelected(this.getRowId(l)), h = this._scrollLeft, g = 0, _ = this.selectable ? a`
       <div class="ft-checkbox-cell"
         style="position: absolute; top: 0; left: ${h + g}px; width: ${this._checkboxColWidth}px; height: ${d}px; z-index: 2;">
         <!-- 행 체크박스는 Tab 정지점이 아니다 — 그리드(호스트)가 하나의 정지점이고 행 선택은 Shift+Space 다.
@@ -4426,7 +4472,7 @@ G([c({ type: Array })], Q.prototype, "columns", void 0), G([c({
 })], Q.prototype, "clearUndoOnDataChange", void 0), G([c({
 	type: Boolean,
 	attribute: "clear-selection-on-data-change"
-})], Q.prototype, "clearSelectionOnDataChange", void 0), G([c({
+})], Q.prototype, "clearSelectionOnDataChange", void 0), G([c({ attribute: "row-key" })], Q.prototype, "rowKey", void 0), G([c({
 	type: Number,
 	attribute: "row-height"
 })], Q.prototype, "rowHeight", null), G([c({

package/dist/flex-table.d.ts

@@ -28,15 +28,22 @@ export declare class FlexTable extends LitElement {
     /**
      * When true, replacing `data` externally automatically clears row selection
      * (checkbox selection) and re-dispatches `selection-change` with an empty selection.
-     * Default: false, for consistency with `clearUndoOnDataChange`. Internal undo/redo
-     * operations are never affected.
-     *
-     * Row selection is index-based (no row-key concept), so a full `data` replacement can
-     * leave selection pointing at different underlying rows at the same indices —
-     * recommended for any `selectable` grid whose selection drives bulk actions
-     * (e.g. server-mode grids refreshed via `useODataSource`).
+     * Default: false — keyed rows stay selected across a replacement (see `rowKey`), so a
+     * selection can span server pages. Set it when a new `data` should start a new selection
+     * (a new search). Internal undo/redo operations are never affected.
      */
     clearSelectionOnDataChange: boolean;
+    /**
+     * What names a row: the field whose value identifies it (default `'_id'`, as in `u-rich-table`),
+     * or a function of the row. Row selection is kept by this id (`getRowId`), so checkmarks stay on
+     * their rows through sorting, filtering, inserts and deletes — and, for rows that have a key,
+     * across a `data` replacement: another server page keeps the rows selected on the last one.
+     *
+     * A row whose key is missing (`undefined`, `null` or `''`) is named by the row object itself —
+     * a session-local id `#n`. It follows the row while the same object is in `data`, and leaves the
+     * selection when `data` no longer holds that object (a replacement with new objects).
+     */
+    rowKey: string | ((row: DataRow) => unknown);
     /**
      * 행 높이(px).
      *
@@ -135,8 +142,12 @@ export declare class FlexTable extends LitElement {
     private _sortedIndices;
     private _openFilterKey;
     private _rowSelectionVersion;
-    /** Anchor row for shift-click range selection on the row checkbox column. */
-    private _lastCheckboxRowIndex;
+    /** Anchor row (its id) for shift-click range selection on the row checkbox column. */
+    private _lastCheckboxRowId;
+    /** Session-local ids of rows that have no key — by object, so they follow the row and leave with it. */
+    private _unkeyedIds;
+    private _unkeyedSeq;
+    private _visibleIdsCache;
     /** Set by the checkbox's own click (which carries shiftKey) just before its change event fires. */
     private _checkboxShiftPending;
     private _autocompleteState;
@@ -179,14 +190,29 @@ export declare class FlexTable extends LitElement {
     get sortCriteria(): SortCriteria[];
     /** Number of rows after filtering (before pagination). */
     get filteredRowCount(): number;
-    /** Get data indices of currently selected rows. */
+    /**
+     * The row selection. `selectedIds` is every selected row — on every page, including rows not in
+     * `data` now. `selectedRows` and `selectedIndices` are the selected rows that `data` holds (in
+     * `data` order, filtered-out rows included) and their positions in it.
+     */
     getSelectedRows(): {
+        selectedIds: string[];
         selectedIndices: number[];
         selectedRows: DataRow[];
     };
-    /** Select all visible rows (multi mode only). */
+    /** The id row selection keeps for `row` — its `rowKey` value as a string, or `#n` for a row without one. */
+    getRowId(row: DataRow): string;
+    /** Ids of the selected rows — every page, including rows not in `data` now. A copy. */
+    get selectedRowIds(): ReadonlySet<string>;
+    /**
+     * Replaces the row selection with `ids` (single mode keeps the last). Does nothing — and fires
+     * nothing — when the selection already is `ids`, so a host can set it from its own state on
+     * every render.
+     */
+    setSelection(ids: Iterable<string>): void;
+    /** Selects every row in view — after filtering (multi mode only). Rows on other pages stay as they are. */
     selectAll(): void;
-    /** Deselect all rows. */
+    /** Deselects every row — on every page. */
     deselectAll(): void;
     /**
      * Selects every currently-loaded row for which `predicate` returns true, in addition to
@@ -200,6 +226,10 @@ export declare class FlexTable extends LitElement {
      */
     selectWhere(predicate: (row: DataRow, dataIndex: number) => boolean): void;
     private _dispatchRowSelectionEvent;
+    /** Ids of the rows in view, top to bottom (after filter and sort). Cached per view and `rowKey`. */
+    private _visibleRowIds;
+    /** Drops selected `#n` ids whose rows `data` no longer holds. Returns whether anything was dropped. */
+    private _pruneGoneUnkeyedRows;
     /**
      * Set a filter for a column. Replaces any existing filter on the same key.
      */
@@ -263,8 +293,9 @@ export declare class FlexTable extends LitElement {
      */
     addRow(row?: DataRow, index?: number): DataRow | null;
     /**
-     * Delete rows at the specified data indices.
-     * If no indices provided, deletes the currently selected rows.
+     * Delete rows at the specified data indices. Without indices it deletes the selected rows: the
+     * checked rows when the grid is `selectable` (none checked — nothing is deleted), otherwise the
+     * rows of the cell selection.
      */
     deleteRows(indices?: number[]): void;
     /**

package/dist/flex-table.js

@@ -1,3 +1,3 @@
-import { a as e, i as t, n, o as r, r as i, t as a } from "./flex-table-D3E9npd9.js";
+import { a as e, i as t, n, o as r, r as i, t as a } from "./flex-table-M_oC8OXD.js";
 import { t as o } from "./locale-Cfm-vJji.js";
 export { a as FlexTable, e as RowSelectionState, t as UndoStack, n as effectiveAlign, i as exportData, o as flexTableLocale, r as renderCell };

package/dist/react.js

@@ -1,4 +1,4 @@
-import { t as e } from "./flex-table-D3E9npd9.js";
+import { t as e } from "./flex-table-M_oC8OXD.js";
 import { i as t } from "./query-Dw4iO0ir.js";
 import { t as n } from "./source--q5s2Oti.js";
 import { t as r } from "./view-DiLr-TdY.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/flex-table",
-  "version": "0.55.2",
+  "version": "0.56.0",
   "description": "A minimalist, input-centric data grid web component",
   "type": "module",
   "main": "./dist/flex-table.js",

package/skills/iyulab-flex-table/SKILL.md

@@ -78,9 +78,12 @@ Use `updateRows([{ row, key, value }])` for programmatic edits (undoable, fires
 `table.editable = false` (a property, since a boolean attribute cannot express `false`) — Enter on a non-editable cell then fires
 `row-activate`, the grid's "open this row" contract.
 
-**Row selection is index-based.** Enable with `selectable` (`selection-mode="single|multi"`).
-There is no row key, so set `clear-selection-on-data-change` when selection drives bulk actions and
-`data` can be replaced. `selectWhere(predicate)` selects rows by content.
+**Row selection is kept by row id.** Enable with `selectable` (`selection-mode="single|multi"`).
+The id is the row's `row-key` field (`_id` by default, as in `u-rich-table`) or a `rowKey` function, so
+checkmarks follow their rows through sort, filter, insert and delete, and keyed rows stay selected
+across server pages (`selectedIds`). A row without a key is named by its object and leaves the selection
+when `data` drops it. `clear-selection-on-data-change` starts a new selection on every `data`.
+`selectWhere(predicate)` selects rows by content; `setSelection(ids)` sets it from host state.
 
 **Client vs server mode.** `data-mode="client"` (default) sorts and filters locally.
 `data-mode="server"` only emits `sort-change` / `filter-change`; you supply already-processed rows.

package/skills/iyulab-flex-table/references/api.md

@@ -27,7 +27,8 @@ All names below are members of the `FlexTable` class (`<flex-table>`).
 | `loading` | `loading` | `boolean` | `false` | Loading overlay + `aria-busy` |
 | `importEnabled` | `import-enabled` | `boolean` | `false` | Drag-and-drop `.xlsx` / `.csv` import |
 | `clearUndoOnDataChange` | `clear-undo-on-data-change` | `boolean` | `false` | Replacing `data` clears undo history |
-| `clearSelectionOnDataChange` | `clear-selection-on-data-change` | `boolean` | `false` | Replacing `data` clears row selection |
+| `clearSelectionOnDataChange` | `clear-selection-on-data-change` | `boolean` | `false` | Replacing `data` clears row selection (otherwise keyed rows stay selected across pages) |
+| `rowKey` | `row-key` | `string \| (row) => unknown` | `'_id'` | Names a row; selection is kept by this id. A row without a key gets a session-local `#n` |
 | `stylesheets` | — | `CSSStyleSheet[]` | `[]` | Adopted into the shadow root; styles `render` output |
 
 Replacing `data` with the same array reference does not trigger the clear-on-change behaviors.
@@ -95,7 +96,7 @@ Enter/Escape and blur-to-commit behavior.
 | Method | Returns | Notes |
 |---|---|---|
 | `addRow(row?, index?)` | `DataRow \| null` | `null` when `maxRows` reached |
-| `deleteRows(indices?)` | `void` | Data indices; default = selected rows |
+| `deleteRows(indices?)` | `void` | Data indices; default = the checked rows when `selectable`, else the cell selection's rows |
 | `updateRows(changes)` | `void` | `Array<{ row, key, value }>`, one undo step |
 | `refreshData()` | `void` | Re-render after in-place mutation |
 
@@ -115,9 +116,11 @@ Enter/Escape and blur-to-commit behavior.
 
 | Method | Notes |
 |---|---|
-| `selectAll()` / `deselectAll()` | `selectAll` is multi mode only |
+| `selectAll()` / `deselectAll()` | `selectAll`: the rows in view (multi mode only) · `deselectAll`: every page |
 | `selectWhere(predicate)` | `(row, dataIndex) => boolean` over the visible rows |
-| `getSelectedRows()` | `{ selectedIndices, selectedRows }` |
+| `setSelection(ids)` | Replace with these row ids; the same set again fires nothing |
+| `getSelectedRows()` | `{ selectedIds, selectedIndices, selectedRows }` — ids: all pages · rows: the ones `data` holds |
+| `getRowId(row)` · `selectedRowIds` | A row's id · the selected ids (all pages) |
 
 ### Filtering, undo, comments, import/export
 
@@ -147,7 +150,7 @@ cast, and the React `on*` props carry the same types.
 | `validation-error` | `{ row, col, key, value, error }` |
 | `row-add` | `{ row, index }` |
 | `row-delete` | `{ indices, rows }` |
-| `row-activate` | `{ row, index, col, key }` — Enter on a non-editable cell |
+| `row-activate` | `{ row, id, index, col, key }` — Enter on a non-editable cell |
 | `row-reorder` | `{ from, to }` |
 | `batch-update` | `{ changes }` |
 | `column-add` | `{ column, index }` |
@@ -159,7 +162,7 @@ cast, and the React `on*` props carry the same types.
 | `sort-change` | `{ criteria }` |
 | `filter-change` | `{ keys, filteredCount }` |
 | `filter-error` | `{ error, row, filterKey }` |
-| `selection-change` | `{ selectedIndices, selectedRows }` |
+| `selection-change` | `{ selectedIds, selectedIndices, selectedRows }` |
 | `clipboard-copy` / `clipboard-cut` | `{ range, text }` (TSV) |
 | `clipboard-paste` | `{ changes, addedRows }` |
 | `clipboard-error` | `{ action: 'copy' \| 'paste', error }` — copy could not put the text on the clipboard (no `clipboard-copy`/`clipboard-cut` follows; a cut clears nothing), or paste could not read it |

package/skills/iyulab-flex-table/references/react.md

@@ -78,7 +78,6 @@ function Orders() {
         loading={source.loading}
         error={source.error}
         onSortChange={source.onSortChange}
-        clearSelectionOnDataChange
       />
       <button disabled={source.page === 0} onClick={() => source.setPage(source.page - 1)}>Prev</button>
       <span>{source.page + 1} / {Math.max(1, Math.ceil(source.totalCount / 20))}</span>