@iyulab/flex-table 0.55.2 → 0.56.1

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [0.56.1] - 2026-10-07
+
+### Fixed
+
+- **An edit is written to the row it was started on.** The open editor remembered a screen position and the commit
+  wrote whatever row stood there, so a refresh that put a row above the one being edited (or a sort while editing)
+  sent the typed value into another row. The editor now follows its row — drawn again in the row's new place with
+  what was typed and the focus — and an edit whose row left `data` (or a filter hid) is cancelled.
+- **Undo and redo write the rows they changed** (cell edits, `updateRows`, paste, clear, fill, replace). They wrote
+  `data` positions, so after `data` changed in between they changed other rows.
+- **Comments stay on their rows.** They were kept by `data` index, so inserting or deleting a row moved every comment
+  below it onto the neighbouring row. A deleted row's comments leave with it (and come back on undo).
+- **Validation marks stay on their cells** when the view reorders while one is shown.
+- `cell-edit-cancel` reports `row` as the data index, like the other edit events (it was the screen position) —
+  `-1` when the row is no longer in `data`.
+
+### Added
+
+- `comment-change` and `getAllComments()` carry the row's `id`.
+
+## [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>
@@ -295,7 +306,7 @@ type-checks without a cast. The React wrapper's `on*` props carry the same types
 | `cell-select` | `{ row, col }` or `null` | Cell focus changed (`null` when no cell is active) |
 | `cell-edit-start` | `{ row, col, key, value }` | Cell editing started |
 | `cell-edit-commit` | `{ row, col, key, oldValue, newValue }` | Cell value committed |
-| `cell-edit-cancel` | `{ row, col }` | Cell edit cancelled (Escape) |
+| `cell-edit-cancel` | `{ row, col }` | Cell edit cancelled (Escape, or its row left `data`). `row` is the data index (`-1` once the row is gone) |
 | `validation-error` | `{ row, col, key, value, error }` | Cell validator rejected value, or a `number` cell got text that is not a number |
 
 ### Data Events
@@ -304,13 +315,13 @@ 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 |
 | `fill-handle-apply` | `{ sourceRange, targetRange, cells }` | Fill handle wrote `cells` (`{ dataRow, key, oldValue, newValue }`) |
 | `find-replace` | `{ type, cells }` | Replace (`type: 'replace'`) or replace-all from the find panel; `cells` are `{ row, col, oldValue, newValue }` with `col` the column key |
-| `comment-change` | `{ dataIndex, colKey, text }` | Cell comment set, changed or removed (`text: null`) |
+| `comment-change` | `{ dataIndex, id, colKey, text }` | Cell comment set, changed or removed (`text: null`). Comments stay on their rows (`id`) when rows move |
 
 ### Column Events
 
@@ -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/editing.d.ts

@@ -1,14 +1,20 @@
 import type { CellPosition } from './selection.js';
+import type { DataRow } from '../models/types.js';
 export interface EditState {
+    /** Where the editor is drawn — the visual cell. The grid moves it when the view moves the row. */
     position: CellPosition;
     originalValue: unknown;
+    /** The row being edited — the commit writes it, wherever `data` has moved it. */
+    row: DataRow;
+    /** What the editor held when the row moved and the editor was drawn again — handed to the new one. */
+    draft?: unknown;
 }
 /**
  * Manages cell editing state.
  */
 export declare class EditingState {
     current: EditState | null;
-    start(position: CellPosition, originalValue: unknown): void;
+    start(position: CellPosition, originalValue: unknown, row: DataRow): void;
     isEditing(row: number, col: number): boolean;
     cancel(): EditState | null;
     commit(): EditState | null;

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;
@@ -122,8 +126,10 @@ export interface FlexTableEventMap {
         value: unknown;
         error: string;
     }>;
+    /** `id` — the row's id (comments stay on their rows); `dataIndex` — its position in `data` now (-1 when not loaded). */
     'comment-change': CustomEvent<{
         dataIndex: number;
+        id: string;
         colKey: string;
         text: string | null;
     }>;