@ixfx/components 0.15.5 → 0.16.0

package/dist/{data-grid-C1sZX6n9.js → data-grid-rMkLX2qo.js}

@@ -6,7 +6,9 @@ import "./icon-1gpwtPx8.js";
 import { i as ListSearchController, n as listSearchStyles, o as registerListSearchCommands, r as LIST_SEARCH_MODES } from "./incr-search-JIhwB49y.js";
 import { t as handleStyles } from "./handle-DAXs7kbJ.js";
 import { a as listItemFadeKeyframes, t as ListNativeDragController } from "./list-native-drag-controller-CcXoS0YX.js";
+import { a as capKeys, l as keysToArray, n as EMPTY_KEYS, o as flagsFromRecord, r as MAX_PENDING_KEYS } from "./pending-BGidHppL.js";
 import "./interaction-E-uMGHkJ.js";
+import { n as anchorFromRow, o as scrollToOffset, t as ViewStateController } from "./view-state-controller-BdyXWUUM.js";
 import { t as scrollFadeStyles } from "./scroll-fade-Xx28D7mH.js";
 import { n as appearanceColor, t as appearanceAbsent } from "./item-appearance-BjcMyauw.js";
 import { t as createDragGhost } from "./drag-ghost-DtSDvjri.js";
@@ -16,6 +18,191 @@ import { LitElement, css, html, nothing } from "lit";
 import { property, query, state } from "lit/decorators.js";
 import { createCommandRegistry } from "@clinth/ui-commands";
 import { repeat } from "lit/directives/repeat.js";
+//#region src/data-grid/data-grid-view-state.ts
+const EMPTY_COLUMNS = /* @__PURE__ */ new Map();
+const EMPTY_ORDER = /* @__PURE__ */ new Map();
+/**
+* Selected keys whose row is gone go pending (deselected silently); pending
+* keys whose row now exists are selected unless `canRestore` is false (e.g.
+* `selectionMode="none"`), in which case they stay pending. With `single`, at
+* most one key stays selected (a restored key wins) and nothing more stays
+* pending.
+*/
+function reconcileSelectedKeys(selected, pending, has, single, canRestore = true) {
+	if (selected.size === 0 && pending.size === 0) return {
+		selected,
+		pending,
+		restored: false,
+		changed: false
+	};
+	let next;
+	let nextPending;
+	for (const key of selected) {
+		if (has(key)) continue;
+		next ??= new Set(selected);
+		next.delete(key);
+		nextPending ??= new Set(pending);
+		nextPending.add(key);
+	}
+	const present = canRestore ? [...pending].filter(has) : [];
+	const resolved = resolvePendingKeys(next ?? selected, nextPending ?? pending, present, single);
+	return {
+		...resolved,
+		changed: resolved.changed || next !== void 0
+	};
+}
+/**
+* Select the `present` pending keys (already known to exist). Used on its own
+* for streamed appends, where only the new slice can match — so the cost is
+* proportional to the slice, not the row count.
+*/
+function resolvePendingKeys(selected, pending, present, single) {
+	if (present.length === 0) return {
+		selected,
+		pending: capKeys(pending),
+		restored: false,
+		changed: false
+	};
+	const next = new Set(selected);
+	const nextPending = new Set(pending);
+	for (const key of present) {
+		next.add(key);
+		nextPending.delete(key);
+	}
+	if (single) return {
+		selected: /* @__PURE__ */ new Set([present.at(-1)]),
+		pending: EMPTY_KEYS,
+		restored: true,
+		changed: true
+	};
+	return {
+		selected: next,
+		pending: capKeys(nextPending),
+		restored: true,
+		changed: true
+	};
+}
+/** Pending keys that appear in `sliceKeys` — iterates the slice, not the pending set. */
+function matchSlice(pending, sliceKeys) {
+	if (pending.size === 0) return [];
+	return sliceKeys.filter((k) => pending.has(k));
+}
+/** Collapsed group keys as an `expanded` record (`false` = collapsed). */
+function collapsedToRecord(collapsed, include = () => true) {
+	const out = {};
+	for (const key of collapsed) if (include(key)) out[key] = false;
+	return out;
+}
+/** `expanded` record → collapsed group keys. Groups default open, so only `false` matters. */
+function collapsedFromRecord(record) {
+	const keys = [...flagsFromRecord(record)].filter(([, open]) => !open).map(([k]) => k);
+	return new Set(capKeys(new Set(keys)));
+}
+/** Parse a saved `columns` record into pending layout and a saved order. Invalid values are dropped. */
+function columnStateFromRecord(record) {
+	const pending = /* @__PURE__ */ new Map();
+	const order = /* @__PURE__ */ new Map();
+	for (const [key, s] of Object.entries(record)) {
+		if (s === null || typeof s !== `object`) continue;
+		const width = typeof s.width === `number` && Number.isFinite(s.width) && s.width > 0 ? s.width : void 0;
+		const visible = typeof s.visible === `boolean` ? s.visible : void 0;
+		if (width !== void 0 || visible !== void 0) pending.set(key, {
+			...width === void 0 ? {} : { width },
+			...visible === void 0 ? {} : { visible }
+		});
+		if (typeof s.order === `number` && Number.isFinite(s.order)) order.set(key, s.order);
+	}
+	return {
+		pending,
+		order
+	};
+}
+/**
+* - columns in `prev` but not in `columns` → their width / visibility go pending
+* - pending layout for columns now defined → applied (on a copy of the column)
+* - a saved `order` reorders the columns it names within the slots they
+*   occupy, leaving other columns where they are; it is dropped once every
+*   column it names is defined (so the host can reorder freely afterwards)
+*
+* Returns the input array when nothing changed, so `columns` identity (a sort
+* input) only changes when it must.
+*/
+function reconcileColumns(prev, columns, pending, order) {
+	const keys = new Set(columns.map((c) => c.key));
+	let nextPending;
+	for (const col of prev) {
+		if (keys.has(col.key) || pending.has(col.key)) continue;
+		nextPending ??= new Map(pending);
+		nextPending.set(col.key, layoutOf(col));
+	}
+	let next;
+	columns.forEach((col, i) => {
+		const saved = (nextPending ?? pending).get(col.key);
+		if (!saved) return;
+		nextPending ??= new Map(pending);
+		nextPending.delete(col.key);
+		if ((saved.width === void 0 || saved.width === col.width) && (saved.visible === void 0 || saved.visible === (col.visible !== false))) return;
+		next ??= [...columns];
+		next[i] = {
+			...col,
+			...saved
+		};
+	});
+	let nextOrder = order;
+	if (order.size > 0) {
+		const working = next ?? columns;
+		const slots = working.flatMap((c, i) => order.has(c.key) ? [i] : []);
+		const ranked = slots.map((i) => working[i]).sort((a, b) => order.get(a.key) - order.get(b.key));
+		if (ranked.some((c, j) => c !== working[slots[j]])) {
+			next ??= [...columns];
+			slots.forEach((slot, j) => {
+				next[slot] = ranked[j];
+			});
+		}
+		if ([...order.keys()].every((k) => keys.has(k))) nextOrder = EMPTY_ORDER;
+	}
+	return {
+		columns: next ?? columns,
+		pending: nextPending ? capMap(nextPending) : pending,
+		order: nextOrder,
+		changed: next !== void 0 || nextPending !== void 0 || nextOrder !== order
+	};
+}
+/** Defined columns (and, with `pending`, saved layout for undefined ones) as a JSON record. */
+function captureColumns(columns, pending, order, includePending) {
+	const out = {};
+	if (includePending) {
+		for (const [key, layout] of pending) out[key] = withOrder(layout, order.get(key));
+		for (const [key, rank] of order) if (!(key in out) && !columns.some((c) => c.key === key)) out[key] = { order: rank };
+	}
+	columns.forEach((col, i) => {
+		out[col.key] = withOrder(layoutOf(col), order.size > 0 ? order.get(col.key) : i);
+	});
+	return out;
+}
+/** Whether `value` is a usable sort state (`null` = unsorted). */
+function isSortState(value) {
+	if (value === null) return true;
+	if (typeof value !== `object`) return false;
+	const s = value;
+	return typeof s.key === `string` && (s.direction === `asc` || s.direction === `desc`);
+}
+function layoutOf(col) {
+	return {
+		...col.width === void 0 ? {} : { width: col.width },
+		visible: col.visible !== false
+	};
+}
+function withOrder(layout, order) {
+	return order === void 0 ? { ...layout } : {
+		...layout,
+		order
+	};
+}
+function capMap(map, max = MAX_PENDING_KEYS) {
+	return map.size <= max ? map : new Map([...map].slice(map.size - max));
+}
+//#endregion
 //#region src/data-grid/shift-wheel.ts
 /**
 * Shift + vertical mouse wheel → horizontal scroll.
@@ -72,12 +259,20 @@ const EMPTY_CELL_LOOK = {
 	iconColor: void 0,
 	badge: void 0
 };
+/**
+* Default `getRowKey`: `row.key`, then `row.id`, else the row's sorted index.
+* Index keys aren't stable, so view state never records them.
+*/
+const defaultGetRowKey = (r, i) => r.key ?? r.id ?? String(i);
 /** Shallow key-array equality, treating `undefined` (never dispatched) as different. */
 function sameKeys(a, b) {
 	if (a === void 0 || a.length !== b.length) return false;
 	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
 	return true;
 }
+function sameSet(a, b) {
+	return a.size === b.size && [...a].every((k) => b.has(k));
+}
 /** Element-wise reference equality, treating `undefined` (never computed) as different. */
 function sameRefs(a, b) {
 	return a !== void 0 && a.length === b.length && a.every((v, i) => v === b[i]);
@@ -91,7 +286,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 		this.interactionMode = `standard`;
 		this.sortState = null;
 		this.rowHeight = 28;
-		this.getRowKey = (r, i) => r.key ?? r.id ?? String(i);
+		this.getRowKey = defaultGetRowKey;
 		this.editable = false;
 		this.editability = `user`;
 		this.cellOverflow = `ellipsis`;
@@ -185,6 +380,15 @@ let DataGridElement = class DataGridElement extends LitElement {
 		this.#viewportChangeRaf = 0;
 		this.#resortRaf = 0;
 		this._drag = null;
+		this.#viewState = new ViewStateController(this, {
+			kind: `data-grid`,
+			capture: () => this.getViewState()
+		});
+		this.#pendingSelected = EMPTY_KEYS;
+		this.#pendingColumns = EMPTY_COLUMNS;
+		this.#columnOrder = EMPTY_ORDER;
+		this.#reconciledColumns = [];
+		this.#groupKeys = /* @__PURE__ */ new Set();
 		this._onFocusOut = (e) => {
 			if (this._suppressBlurCommit) return;
 			if (this.editability === `immediate`) return;
@@ -204,180 +408,18 @@ let DataGridElement = class DataGridElement extends LitElement {
 				this._scrollLeft = el.scrollLeft;
 				const after = this.#windowRows(2);
 				if (before.start !== after.start || before.end !== after.end) this.requestUpdate();
+				if (!this.#viewState.pendingScroll) this.#viewState.notify();
 				cancelAnimationFrame(this.#viewportChangeRaf);
 				this.#viewportChangeRaf = 0;
 				this.#emitViewportChangeIfChanged();
 			});
 		};
 		this._onKeyDown = (e) => {
-			if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === `a`) {
-				if (this.selectionMode === `multiple` || this.interactionMode === `checked` || this.interactionMode === `sticky` || this.interactionMode === `vscode` || this.interactionMode === `standard`) {
-					e.preventDefault();
-					const prev = new Set(this._selectedKeys);
-					if (this.groupBy && !this.crossGroupSelection && this._anchorKey) {
-						const g = this._getGroupKey(this._getRowForKey(this._anchorKey) ?? { key: this._anchorKey });
-						this._selectedKeys = new Set(this._flat.filter((f) => f.type === `row` && this._getGroupKey(f.row) === g).map((f) => f.key));
-					} else this._selectedKeys = new Set(this._flat.filter((f) => f.type === `row`).map((f) => f.key));
-					this.dispatchEvent(new CustomEvent(`datagrid-select`, {
-						detail: {
-							selectedKeys: new Set(this._selectedKeys),
-							previous: prev
-						},
-						bubbles: true,
-						composed: true
-					}));
-				}
-				return;
-			}
-			if (this._editing && (e.key === `ArrowDown` || e.key === `ArrowUp`)) {
-				if ((this.shadowRoot?.activeElement)?.tagName === `SELECT`) return;
-				e.preventDefault();
-				const cur = this._editing;
-				const dir = e.key === `ArrowDown` ? 1 : -1;
-				const colKey = cur.colKey;
-				this._suppressBlurCommit = true;
-				this._commitEdit();
-				const rowKeys = this._flat.filter((f) => f.type === `row`).map((f) => f.key);
-				const idx = rowKeys.indexOf(cur.rowKey);
-				let nextIdx = idx + dir;
-				while (nextIdx >= 0 && nextIdx < rowKeys.length) {
-					const nk = rowKeys[nextIdx];
-					const row = this.#rowEntry(nk)?.row;
-					const col = this._visibleColumns.find((c) => c.key === colKey);
-					if (row && col && this._isEditable(row, col)) {
-						this._startEdit(nk, colKey);
-						this._tickled.handleKeyboardNavigation(nextIdx > idx ? `next` : `previous`);
-						this._scrollRowIntoView(nk);
-						break;
-					}
-					nextIdx += dir;
-				}
-				if (nextIdx < 0 || nextIdx >= rowKeys.length) {
-					this._tickled.handleKeyboardNavigation(dir > 0 ? `next` : `previous`);
-					if (this._tickled.tickledId) this._scrollRowIntoView(this._tickled.tickledId);
-				}
-				requestAnimationFrame(() => {
-					this._suppressBlurCommit = false;
-				});
-				return;
-			}
-			if (e.key === `ArrowDown` || e.key === `ArrowUp` || e.key === `Home` || e.key === `End`) {
-				e.preventDefault();
-				this._tickled.setInputMode(`keyboard`);
-			}
-			switch (e.key) {
-				case `ArrowDown`:
-					this._tickled.handleKeyboardNavigation(`next`);
-					if (this._tickled.tickledId) this._scrollRowIntoView(this._tickled.tickledId);
-					if (this.interactionMode === `implicit` && this._tickled.tickledId) this._replaceSelection(this._tickled.tickledId);
-					if (e.shiftKey && (this.interactionMode === `standard` || this.interactionMode === `vscode`) && this._tickled.tickledId) this._rangeSelectTo(this._tickled.tickledId);
-					break;
-				case `ArrowUp`:
-					this._tickled.handleKeyboardNavigation(`previous`);
-					if (this._tickled.tickledId) this._scrollRowIntoView(this._tickled.tickledId);
-					if (this.interactionMode === `implicit` && this._tickled.tickledId) this._replaceSelection(this._tickled.tickledId);
-					if (e.shiftKey && (this.interactionMode === `standard` || this.interactionMode === `vscode`) && this._tickled.tickledId) this._rangeSelectTo(this._tickled.tickledId);
-					break;
-				case `Home`:
-					this._tickled.handleKeyboardNavigation(`first`);
-					if (this._tickled.tickledId) this._scrollRowIntoView(this._tickled.tickledId);
-					break;
-				case `End`:
-					this._tickled.handleKeyboardNavigation(`last`);
-					if (this._tickled.tickledId) this._scrollRowIntoView(this._tickled.tickledId);
-					break;
-				case `Enter`: {
-					const key = this._tickled.tickledId;
-					if (!key) break;
-					e.preventDefault();
-					if (!this._editing && this.editability === `user`) {
-						const entry = this.#rowEntry(key);
-						if (entry) {
-							const row = entry.row;
-							if (this._lastClickedCell?.rowKey === key) {
-								const col = this._visibleColumns.find((c) => c.key === this._lastClickedCell.colKey);
-								if (col && this._isEditable(row, col)) {
-									this._startEdit(key, col.key);
-									break;
-								}
-							}
-							const firstEditable = this._visibleColumns.find((c) => this._isEditable(row, c));
-							if (firstEditable) {
-								this._startEdit(key, firstEditable.key);
-								break;
-							}
-						}
-					}
-					if (!this._editing) {
-						const entry = this.#rowEntry(key);
-						const idx = entry?.idx ?? -1;
-						if (this._selectedKeys.has(key)) {
-							this._activateRow(key, entry?.row, idx);
-							break;
-						}
-						if (this.interactionMode !== `manual` && this.interactionMode !== `checked`) this._replaceSelection(key);
-						this.dispatchEvent(new CustomEvent(`datagrid-cell-click`, {
-							detail: {
-								rowKey: key,
-								colKey: ``,
-								rowIndex: idx,
-								colIndex: -1
-							},
-							bubbles: true,
-							composed: true
-						}));
-					}
-					break;
-				}
-				case ` `: {
-					if (this._editing) {
-						if ((this.columns.find((c) => c.key === this._editing.colKey)?.dataType ?? `text`) === `boolean`) {
-							e.preventDefault();
-							const isImmediate = this.editability === `immediate`;
-							const rowKey = this._editing.rowKey;
-							const colKey = this._editing.colKey;
-							const active = this.shadowRoot?.activeElement;
-							let next;
-							if (active?.type === `checkbox`) {
-								next = !active.checked;
-								active.checked = next;
-							} else {
-								const row = this.#rowEntry(rowKey)?.row;
-								next = !(this._editValue !== `` ? Boolean(this._editValue) : Boolean(row?.[colKey]));
-							}
-							if (isImmediate) this._commitImmediate(rowKey, colKey, next);
-							else {
-								this._editValue = next;
-								this._commitEdit();
-							}
-						}
-						break;
-					}
-					const key = this._tickled.tickledId;
-					if (!key) break;
-					e.preventDefault();
-					if (this.interactionMode === `checked` || this.interactionMode === `sticky` || this.interactionMode === `standard` || this.interactionMode === `vscode` || this.interactionMode === `manual`) this._toggleSelection(key);
-					else this._replaceSelection(key);
-					break;
-				}
-				case `Escape`: if (this._editing || this._editingRow) {
-					e.preventDefault();
-					this._editing = null;
-					this._editingRow = null;
-					this.requestUpdate();
-				} else if (this._selectedKeys.size) {
-					e.preventDefault();
-					const prev = new Set(this._selectedKeys);
-					this._selectedKeys = /* @__PURE__ */ new Set();
-					this.dispatchEvent(new CustomEvent(`datagrid-select`, {
-						detail: {
-							selectedKeys: /* @__PURE__ */ new Set(),
-							previous: prev
-						},
-						bubbles: true,
-						composed: true
-					}));
-				}
+			const before = this._tickled.tickledId;
+			this.#handleKeyDown(e);
+			if (this._tickled.tickledId !== before) {
+				this.#pendingFocus = void 0;
+				this.#viewState.notify();
 			}
 		};
 		this._suppressBlurCommit = false;
@@ -711,6 +753,21 @@ let DataGridElement = class DataGridElement extends LitElement {
 	#lastViewportVisibleKeys;
 	#resortRaf;
 	#detachShiftWheel;
+	#viewState;
+	/** Saved selection for row keys not (yet) in `rows`. */
+	#pendingSelected;
+	#pendingFocus;
+	/** Saved width / visibility for column keys not (yet) in `columns`. */
+	#pendingColumns;
+	/** Saved column order, kept until every column it names is defined. */
+	#columnOrder;
+	/** `columns` as of the last column reconcile, to spot removed columns. */
+	#reconciledColumns;
+	/** Every row by key, built lazily (only when a key isn't in `_flat`); reset on resort. */
+	#rowIndex;
+	#rowIndexKeyFn;
+	/** Group keys in the current flat model. */
+	#groupKeys;
 	connectedCallback() {
 		super.connectedCallback();
 		if (!this.hasAttribute(`tabindex`)) this.tabIndex = 0;
@@ -754,6 +811,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 		this.#viewportResizeObserver = new ResizeObserver(() => this.#measureViewport());
 		this.#viewportResizeObserver.observe(this._viewportEl);
 		this.#measureViewport();
+		this.#viewState.observeScrollTarget(this._viewportEl);
 	}
 	/**
 	* Re-read the viewport's size and update `_viewportH`/`_viewportW` if it
@@ -788,6 +846,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 	}
 	updated(changed) {
 		super.updated(changed);
+		this.#viewState.applyPendingScroll((s) => this.#applyScroll(s));
 		if (changed.has(`rows`) || changed.has(`sortState`) || changed.has(`columns`) || changed.has(`groupBy`) || changed.has(`groupLabel`) || changed.has(`filterPredicate`) || changed.has(`rowHeight`)) this.#scheduleViewportChangeEmit();
 		if (changed.has(`_editing`) || changed.has(`_editingRow`)) this.updateComplete.then(() => {
 			let sel = null;
@@ -803,7 +862,8 @@ let DataGridElement = class DataGridElement extends LitElement {
 		super.willUpdate(changed);
 		this.setAttribute(`data-input-mode`, this._tickled.inputMode);
 		if (changed.has(`searchModes`)) this.#syncSearchCommands();
-		this.#syncDerivedRows();
+		if (changed.has(`columns`)) this.#reconcileColumns();
+		if (this.#syncDerivedRows()) this.#reconcileRows();
 		this._visibleColumns = this.columns.filter((c) => c.visible !== false);
 		let off = 0;
 		this._colOffsets = this._visibleColumns.map((c) => {
@@ -840,11 +900,14 @@ let DataGridElement = class DataGridElement extends LitElement {
 		if (resort) {
 			this.#sortInputs = sortInputs;
 			this._sortedRows = this._applySort([...this.rows]);
+			this.#rowIndex = void 0;
 		}
 		if (resort || !sameRefs(this.#flatInputs, flatInputs)) {
 			this.#flatInputs = flatInputs;
 			this._rebuildFlat();
+			return true;
 		}
+		return false;
 	}
 	/** Mark the derived rows as matching the current inputs (after an incremental update). */
 	#markDerivedRowsSynced() {
@@ -904,6 +967,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 		for (let i = 0; i < this._sortedRows.length; i++) if (!pred || pred(this._sortedRows[i])) sourceIdx.push(i);
 		const flat = [];
 		const keys = [];
+		this.#groupKeys = /* @__PURE__ */ new Set();
 		const pushRow = (idx) => {
 			const row = this._sortedRows[idx];
 			const key = this.getRowKey(row, idx);
@@ -924,6 +988,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 				if (arr) arr.push(idx);
 				else groups.set(k, [idx]);
 			}
+			this.#groupKeys = new Set(groups.keys());
 			for (const [gKey, idxs] of groups) {
 				const label = this.groupLabel ? this.groupLabel(gKey, idxs.map((i) => this._sortedRows[i])) : gKey;
 				const gId = `__group__${gKey}`;
@@ -963,6 +1028,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 		if (next.has(gKey)) next.delete(gKey);
 		else next.add(gKey);
 		this._collapsedGroups = next;
+		this.#viewState.notify();
 	}
 	_applySort(rows) {
 		if (!this.sortState) return rows;
@@ -1001,6 +1067,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 		};
 		else next = null;
 		this.sortState = next;
+		this.#viewState.notify();
 		this.dispatchEvent(new CustomEvent(`datagrid-sort`, {
 			detail: {
 				sort: next,
@@ -1071,6 +1138,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 	_onVisibilityToggle(col, checked) {
 		col.visible = checked;
 		this.columns = [...this.columns];
+		this.#viewState.notify();
 		this.dispatchEvent(new CustomEvent(`datagrid-column-visibility`, {
 			detail: {
 				key: col.key,
@@ -1175,6 +1243,8 @@ let DataGridElement = class DataGridElement extends LitElement {
 		const [moved] = vis.splice(fromIdx, 1);
 		vis.splice(toIdx, 0, moved);
 		this.columns = [...vis, ...hidden];
+		this.#columnOrder = EMPTY_ORDER;
+		this.#viewState.notify();
 		this.dispatchEvent(new CustomEvent(`datagrid-column-reorder`, {
 			detail: {
 				from: fromIdx,
@@ -1222,10 +1292,10 @@ let DataGridElement = class DataGridElement extends LitElement {
 	* set when the selection actually changes.
 	*/
 	selectKeys(keys) {
+		this.#pendingSelected = EMPTY_KEYS;
 		let next = new Set([...keys].filter((k) => this._getRowForKey(k) !== void 0));
-		const multi = this.selectionMode === `multiple` || this.interactionMode === `checked` || this.interactionMode === `sticky` || this.interactionMode === `vscode`;
 		if (this.selectionMode === `none`) next = /* @__PURE__ */ new Set();
-		else if (!multi && next.size > 1) {
+		else if (!this.#isMultiSelect() && next.size > 1) {
 			const last = [...next].at(-1);
 			next = last === void 0 ? /* @__PURE__ */ new Set() : /* @__PURE__ */ new Set([last]);
 		}
@@ -1233,10 +1303,18 @@ let DataGridElement = class DataGridElement extends LitElement {
 		if (prev.size === next.size && [...next].every((k) => prev.has(k))) return;
 		this._selectedKeys = next;
 		this._anchorKey = [...next].at(-1);
+		this.#dispatchSelect(prev);
+	}
+	#isMultiSelect() {
+		return this.selectionMode === `multiple` || this.interactionMode === `checked` || this.interactionMode === `sticky` || this.interactionMode === `vscode`;
+	}
+	#dispatchSelect(previous) {
+		if (!this.#viewState.isRestoring) this.#pendingSelected = EMPTY_KEYS;
+		this.#viewState.notify();
 		this.dispatchEvent(new CustomEvent(`datagrid-select`, {
 			detail: {
-				selectedKeys: new Set(next),
-				previous: prev
+				selectedKeys: new Set(this._selectedKeys),
+				previous
 			},
 			bubbles: true,
 			composed: true
@@ -1251,6 +1329,8 @@ let DataGridElement = class DataGridElement extends LitElement {
 		if (!this.#flatIndexByKey.has(key) || key.startsWith(`__group__`)) return;
 		this._tickled.focus(key);
 		this._scrollRowIntoView(key);
+		this.#pendingFocus = void 0;
+		this.#viewState.notify();
 	}
 	/**
 	* Append rows without the full O(n log n) rebuild that reassigning `rows`
@@ -1273,6 +1353,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 		this._sortedRows = [...this._sortedRows, ...appended];
 		this.#appendToFlat(appended, startIdx);
 		this.#markDerivedRowsSynced();
+		this.#resolveAppended(appended, startIdx);
 		if (this.sortState != null) {
 			cancelAnimationFrame(this.#resortRaf);
 			this.#resortRaf = requestAnimationFrame(() => {
@@ -1311,14 +1392,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 			this._selectedKeys = /* @__PURE__ */ new Set([key]);
 		} else this._selectedKeys = /* @__PURE__ */ new Set([key]);
 		this._anchorKey = key;
-		this.dispatchEvent(new CustomEvent(`datagrid-select`, {
-			detail: {
-				selectedKeys: new Set(this._selectedKeys),
-				previous: prev
-			},
-			bubbles: true,
-			composed: true
-		}));
+		this.#dispatchSelect(prev);
 	}
 	_toggleSelection(key) {
 		const prev = new Set(this._selectedKeys);
@@ -1334,14 +1408,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 		}
 		this._selectedKeys = next;
 		this._anchorKey = key;
-		this.dispatchEvent(new CustomEvent(`datagrid-select`, {
-			detail: {
-				selectedKeys: new Set(this._selectedKeys),
-				previous: prev
-			},
-			bubbles: true,
-			composed: true
-		}));
+		this.#dispatchSelect(prev);
 	}
 	_rangeSelectTo(key) {
 		if (!this._anchorKey) {
@@ -1372,28 +1439,171 @@ let DataGridElement = class DataGridElement extends LitElement {
 			const hi = Math.max(ga, gb);
 			const prev = new Set(this._selectedKeys);
 			this._selectedKeys = new Set(groupKeys.slice(lo, hi + 1));
-			this.dispatchEvent(new CustomEvent(`datagrid-select`, {
-				detail: {
-					selectedKeys: new Set(this._selectedKeys),
-					previous: prev
-				},
-				bubbles: true,
-				composed: true
-			}));
+			this.#dispatchSelect(prev);
 			return;
 		}
 		const lo = Math.min(a, b);
 		const hi = Math.max(a, b);
 		const prev = new Set(this._selectedKeys);
 		this._selectedKeys = new Set(keys.slice(lo, hi + 1));
-		this.dispatchEvent(new CustomEvent(`datagrid-select`, {
-			detail: {
-				selectedKeys: new Set(this._selectedKeys),
-				previous: prev
-			},
-			bubbles: true,
-			composed: true
-		}));
+		this.#dispatchSelect(prev);
+	}
+	#handleKeyDown(e) {
+		if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === `a`) {
+			if (this.selectionMode === `multiple` || this.interactionMode === `checked` || this.interactionMode === `sticky` || this.interactionMode === `vscode` || this.interactionMode === `standard`) {
+				e.preventDefault();
+				const prev = new Set(this._selectedKeys);
+				if (this.groupBy && !this.crossGroupSelection && this._anchorKey) {
+					const g = this._getGroupKey(this._getRowForKey(this._anchorKey) ?? { key: this._anchorKey });
+					this._selectedKeys = new Set(this._flat.filter((f) => f.type === `row` && this._getGroupKey(f.row) === g).map((f) => f.key));
+				} else this._selectedKeys = new Set(this._flat.filter((f) => f.type === `row`).map((f) => f.key));
+				this.#dispatchSelect(prev);
+			}
+			return;
+		}
+		if (this._editing && (e.key === `ArrowDown` || e.key === `ArrowUp`)) {
+			if ((this.shadowRoot?.activeElement)?.tagName === `SELECT`) return;
+			e.preventDefault();
+			const cur = this._editing;
+			const dir = e.key === `ArrowDown` ? 1 : -1;
+			const colKey = cur.colKey;
+			this._suppressBlurCommit = true;
+			this._commitEdit();
+			const rowKeys = this._flat.filter((f) => f.type === `row`).map((f) => f.key);
+			const idx = rowKeys.indexOf(cur.rowKey);
+			let nextIdx = idx + dir;
+			while (nextIdx >= 0 && nextIdx < rowKeys.length) {
+				const nk = rowKeys[nextIdx];
+				const row = this.#rowEntry(nk)?.row;
+				const col = this._visibleColumns.find((c) => c.key === colKey);
+				if (row && col && this._isEditable(row, col)) {
+					this._startEdit(nk, colKey);
+					this._tickled.handleKeyboardNavigation(nextIdx > idx ? `next` : `previous`);
+					this._scrollRowIntoView(nk);
+					break;
+				}
+				nextIdx += dir;
+			}
+			if (nextIdx < 0 || nextIdx >= rowKeys.length) {
+				this._tickled.handleKeyboardNavigation(dir > 0 ? `next` : `previous`);
+				if (this._tickled.tickledId) this._scrollRowIntoView(this._tickled.tickledId);
+			}
+			requestAnimationFrame(() => {
+				this._suppressBlurCommit = false;
+			});
+			return;
+		}
+		if (e.key === `ArrowDown` || e.key === `ArrowUp` || e.key === `Home` || e.key === `End`) {
+			e.preventDefault();
+			this._tickled.setInputMode(`keyboard`);
+		}
+		switch (e.key) {
+			case `ArrowDown`:
+				this._tickled.handleKeyboardNavigation(`next`);
+				if (this._tickled.tickledId) this._scrollRowIntoView(this._tickled.tickledId);
+				if (this.interactionMode === `implicit` && this._tickled.tickledId) this._replaceSelection(this._tickled.tickledId);
+				if (e.shiftKey && (this.interactionMode === `standard` || this.interactionMode === `vscode`) && this._tickled.tickledId) this._rangeSelectTo(this._tickled.tickledId);
+				break;
+			case `ArrowUp`:
+				this._tickled.handleKeyboardNavigation(`previous`);
+				if (this._tickled.tickledId) this._scrollRowIntoView(this._tickled.tickledId);
+				if (this.interactionMode === `implicit` && this._tickled.tickledId) this._replaceSelection(this._tickled.tickledId);
+				if (e.shiftKey && (this.interactionMode === `standard` || this.interactionMode === `vscode`) && this._tickled.tickledId) this._rangeSelectTo(this._tickled.tickledId);
+				break;
+			case `Home`:
+				this._tickled.handleKeyboardNavigation(`first`);
+				if (this._tickled.tickledId) this._scrollRowIntoView(this._tickled.tickledId);
+				break;
+			case `End`:
+				this._tickled.handleKeyboardNavigation(`last`);
+				if (this._tickled.tickledId) this._scrollRowIntoView(this._tickled.tickledId);
+				break;
+			case `Enter`: {
+				const key = this._tickled.tickledId;
+				if (!key) break;
+				e.preventDefault();
+				if (!this._editing && this.editability === `user`) {
+					const entry = this.#rowEntry(key);
+					if (entry) {
+						const row = entry.row;
+						if (this._lastClickedCell?.rowKey === key) {
+							const col = this._visibleColumns.find((c) => c.key === this._lastClickedCell.colKey);
+							if (col && this._isEditable(row, col)) {
+								this._startEdit(key, col.key);
+								break;
+							}
+						}
+						const firstEditable = this._visibleColumns.find((c) => this._isEditable(row, c));
+						if (firstEditable) {
+							this._startEdit(key, firstEditable.key);
+							break;
+						}
+					}
+				}
+				if (!this._editing) {
+					const entry = this.#rowEntry(key);
+					const idx = entry?.idx ?? -1;
+					if (this._selectedKeys.has(key)) {
+						this._activateRow(key, entry?.row, idx);
+						break;
+					}
+					if (this.interactionMode !== `manual` && this.interactionMode !== `checked`) this._replaceSelection(key);
+					this.dispatchEvent(new CustomEvent(`datagrid-cell-click`, {
+						detail: {
+							rowKey: key,
+							colKey: ``,
+							rowIndex: idx,
+							colIndex: -1
+						},
+						bubbles: true,
+						composed: true
+					}));
+				}
+				break;
+			}
+			case ` `: {
+				if (this._editing) {
+					if ((this.columns.find((c) => c.key === this._editing.colKey)?.dataType ?? `text`) === `boolean`) {
+						e.preventDefault();
+						const isImmediate = this.editability === `immediate`;
+						const rowKey = this._editing.rowKey;
+						const colKey = this._editing.colKey;
+						const active = this.shadowRoot?.activeElement;
+						let next;
+						if (active?.type === `checkbox`) {
+							next = !active.checked;
+							active.checked = next;
+						} else {
+							const row = this.#rowEntry(rowKey)?.row;
+							next = !(this._editValue !== `` ? Boolean(this._editValue) : Boolean(row?.[colKey]));
+						}
+						if (isImmediate) this._commitImmediate(rowKey, colKey, next);
+						else {
+							this._editValue = next;
+							this._commitEdit();
+						}
+					}
+					break;
+				}
+				const key = this._tickled.tickledId;
+				if (!key) break;
+				e.preventDefault();
+				if (this.interactionMode === `checked` || this.interactionMode === `sticky` || this.interactionMode === `standard` || this.interactionMode === `vscode` || this.interactionMode === `manual`) this._toggleSelection(key);
+				else this._replaceSelection(key);
+				break;
+			}
+			case `Escape`: if (this._editing || this._editingRow) {
+				e.preventDefault();
+				this._editing = null;
+				this._editingRow = null;
+				this.requestUpdate();
+			} else if (this._selectedKeys.size) {
+				e.preventDefault();
+				const prev = new Set(this._selectedKeys);
+				this._selectedKeys = /* @__PURE__ */ new Set();
+				this.#dispatchSelect(prev);
+			}
+		}
 	}
 	_isEditable(row, col) {
 		if (this.editability === `disabled`) return false;
@@ -1609,6 +1819,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 		const w = this._measureAutoWidth(col);
 		col.width = w;
 		this.requestUpdate();
+		this.#viewState.notify();
 		this.dispatchEvent(new CustomEvent(`datagrid-column-resize`, {
 			detail: {
 				key: col.key,
@@ -1636,6 +1847,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 		requestAnimationFrame(() => {
 			col.width = target;
 			this.requestUpdate();
+			this.#viewState.notify();
 			this.dispatchEvent(new CustomEvent(`datagrid-column-resize`, {
 				detail: {
 					key,
@@ -1672,6 +1884,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 			window.removeEventListener(`pointerup`, onUp);
 			this._resizingColKey = void 0;
 			const w = Math.max(col.minWidth ?? 40, Math.min(col.maxWidth ?? 600, startW + ev.clientX - startX));
+			this.#viewState.notify();
 			this.dispatchEvent(new CustomEvent(`datagrid-column-resize`, {
 				detail: {
 					key: col.key,
@@ -1684,6 +1897,179 @@ let DataGridElement = class DataGridElement extends LitElement {
 		window.addEventListener(`pointermove`, onMove);
 		window.addEventListener(`pointerup`, onUp);
 	}
+	/**
+	* Snapshot selection, cursor, scroll, collapsed groups, column layout, sort
+	* and (with `allowGrouping`) grouping as plain JSON, keyed by row / group /
+	* column key. Includes pending state for keys not currently present. Rows
+	* keyed by index (no `key` / `id` under the default `getRowKey`) are never
+	* recorded.
+	*/
+	getViewState(options) {
+		const withPending = options?.includePending ?? true;
+		const cursor = this._tickled.inputMode === `keyboard` ? this._tickled.tickledId : void 0;
+		const focus = cursor !== void 0 && this.#isStableKey(cursor) ? cursor : void 0;
+		const groupBy = this.groupBy === null || typeof this.groupBy === `string` ? this.groupBy : void 0;
+		return this.#viewState.shape({
+			selected: keysToArray([...this._selectedKeys].filter((k) => this.#isStableKey(k)), withPending ? this.#pendingSelected : []),
+			focus: focus ?? (withPending ? this.#pendingFocus : void 0),
+			scroll: (withPending ? this.#viewState.pendingScroll : void 0) ?? this.#captureScroll(),
+			expanded: collapsedToRecord(this._collapsedGroups, (k) => withPending || this.#groupKeys.has(k)),
+			columns: captureColumns(this.columns, this.#pendingColumns, this.#columnOrder, withPending),
+			sort: this.sortState,
+			groupBy: this.allowGrouping ? groupBy : void 0
+		}, options);
+	}
+	/**
+	* Apply saved view state. Fields present replace the current ones; row and
+	* column keys that aren't defined yet are applied as they appear (including
+	* rows streamed in with `appendRows()`).
+	*/
+	setViewState(state) {
+		if (!this.#viewState.accepts(state)) return;
+		this.#viewState.restoring(() => {
+			if (state.columns && typeof state.columns === `object`) {
+				const { pending, order } = columnStateFromRecord(state.columns);
+				this.#pendingColumns = pending;
+				this.#columnOrder = order;
+				this.#reconcileColumns();
+			}
+			if (state.sort !== void 0 && isSortState(state.sort)) this.sortState = state.sort;
+			if (state.groupBy === null || typeof state.groupBy === `string`) this.groupBy = state.groupBy;
+			if (state.expanded && typeof state.expanded === `object`) this._collapsedGroups = collapsedFromRecord(state.expanded);
+			if (state.focus !== void 0) this.#pendingFocus = state.focus;
+			if (state.scroll) this.#viewState.pendingScroll = state.scroll;
+			if (Array.isArray(state.selected)) {
+				const prev = this._selectedKeys;
+				this.#pendingSelected = capKeys(new Set(state.selected.filter((k) => typeof k === `string`)));
+				this._selectedKeys = /* @__PURE__ */ new Set();
+				this.#reconcileRows(prev);
+			} else this.#reconcileRows();
+			this.#viewState.notify();
+		});
+		this.requestUpdate();
+	}
+	clearPendingViewState() {
+		this.#pendingSelected = EMPTY_KEYS;
+		this.#pendingFocus = void 0;
+		this.#pendingColumns = EMPTY_COLUMNS;
+		this.#columnOrder = EMPTY_ORDER;
+		this.#viewState.pendingScroll = void 0;
+		if ([...this._collapsedGroups].some((k) => !this.#groupKeys.has(k))) this._collapsedGroups = new Set([...this._collapsedGroups].filter((k) => this.#groupKeys.has(k)));
+	}
+	/** Apply pending column layout to defined columns; demote layout of removed ones. */
+	#reconcileColumns() {
+		const r = reconcileColumns(this.#reconciledColumns, this.columns, this.#pendingColumns, this.#columnOrder);
+		this.#pendingColumns = r.pending;
+		this.#columnOrder = r.order;
+		this.#reconciledColumns = r.columns;
+		if (r.columns !== this.columns) {
+			this.columns = r.columns;
+			this.#viewState.restoring(() => this.#viewState.notify());
+		}
+	}
+	/**
+	* Re-key selection and cursor onto the current rows: state for rows that
+	* left goes pending (silently), pending state for rows now present is
+	* applied. `baseline` is the selection to report as `previous` when the
+	* caller already replaced it (`setViewState`).
+	*/
+	#reconcileRows(baseline) {
+		this.#viewState.restoring(() => {
+			const sel = reconcileSelectedKeys(this._selectedKeys, this.#pendingSelected, (k) => this.#hasRow(k), !this.#isMultiSelect(), this.selectionMode !== `none`);
+			this.#pendingSelected = sel.pending;
+			if (sel.changed) this.#setRestoredSelection(sel.selected);
+			const before = baseline ?? this._selectedKeys;
+			if (baseline ? !sameSet(baseline, this._selectedKeys) : sel.restored) this.#dispatchSelect(before);
+			const cursor = this._tickled.tickledId;
+			if (cursor !== void 0 && !this.#flatIndexByKey.has(cursor)) {
+				if (this._tickled.inputMode === `keyboard` && this.#isStableKey(cursor)) this.#pendingFocus ??= cursor;
+				this._tickled.clearTickled();
+			}
+			this.#applyPendingFocus();
+		});
+	}
+	/** Streamed append: match pending state against the new slice only (never the whole row set). */
+	#resolveAppended(appended, startIdx) {
+		const wantSelection = this.#pendingSelected.size > 0 && this.selectionMode !== `none`;
+		if (wantSelection || this.#rowIndex !== void 0) {
+			const keys = appended.map((r, j) => this.getRowKey(r, startIdx + j));
+			keys.forEach((k, j) => this.#rowIndex?.set(k, appended[j]));
+			const present = wantSelection ? matchSlice(this.#pendingSelected, keys) : [];
+			if (present.length > 0) this.#viewState.restoring(() => {
+				const prev = this._selectedKeys;
+				const sel = resolvePendingKeys(prev, this.#pendingSelected, present, !this.#isMultiSelect());
+				this.#pendingSelected = sel.pending;
+				this.#setRestoredSelection(sel.selected);
+				this.#dispatchSelect(prev);
+			});
+		}
+		if (this.#pendingFocus !== void 0) this.#viewState.restoring(() => this.#applyPendingFocus());
+	}
+	#setRestoredSelection(selected) {
+		const lastKey = this._anchorKey;
+		this._selectedKeys = new Set(selected);
+		this._anchorKey = lastKey !== void 0 && selected.has(lastKey) ? lastKey : [...selected].at(-1);
+	}
+	#applyPendingFocus() {
+		const key = this.#pendingFocus;
+		if (key === void 0 || this._getRowForKey(key) === void 0) return;
+		this.#pendingFocus = void 0;
+		this._tickled.setInputMode(`keyboard`);
+		this._tickled.setTickled(key);
+		this.#viewState.notify();
+	}
+	/** Whether a row with this key is in `rows` (visible, filtered out or in a collapsed group). */
+	#hasRow(key) {
+		const i = this.#flatIndexByKey.get(key);
+		if (i !== void 0) return this._flat[i].type === `row`;
+		return this.#rowsByKey().has(key);
+	}
+	/** Every row by key — built only when a key isn't in `_flat`, then reused until the next resort. */
+	#rowsByKey() {
+		if (this.#rowIndex === void 0 || this.#rowIndexKeyFn !== this.getRowKey) {
+			this.#rowIndexKeyFn = this.getRowKey;
+			this.#rowIndex = new Map(this._sortedRows.map((r, j) => [this.getRowKey(r, j), r]));
+		}
+		return this.#rowIndex;
+	}
+	/** Index-derived keys (default `getRowKey`, row without `key` / `id`) can't be restored, so aren't recorded. */
+	#isStableKey(key) {
+		if (this.getRowKey !== defaultGetRowKey) return true;
+		const row = this._getRowForKey(key) ?? this.#rowsByKey().get(key);
+		return row !== void 0 && (row.key ?? row.id) !== void 0;
+	}
+	#captureScroll() {
+		const vp = this._viewportEl;
+		if (!vp) return void 0;
+		const top = vp.scrollTop;
+		const rh = this.rowHeight;
+		const first = Math.max(0, Math.floor(top / rh));
+		const end = Math.min(this._flat.length, first + 64);
+		for (let i = first; i < end; i++) {
+			const entry = this._flat[i];
+			if (entry.type === `row`) return anchorFromRow(top, this.#isStableKey(entry.key) ? entry.key : void 0, i * rh, vp.scrollLeft);
+		}
+		return anchorFromRow(top, void 0, 0, vp.scrollLeft);
+	}
+	/** Returns `true` once the saved position is fully reached. */
+	#applyScroll(scroll) {
+		const vp = this._viewportEl;
+		if (!vp) return false;
+		let top = scroll.top;
+		if (scroll.anchor) {
+			const i = this.#flatIndexByKey.get(scroll.anchor.key);
+			if (i === void 0) return false;
+			top = i * this.rowHeight + scroll.anchor.offset;
+		}
+		const reachedY = scrollToOffset(vp, top);
+		const reachedX = scroll.left === void 0 || scrollToOffset(vp, scroll.left, `horizontal`);
+		const before = this.#windowRows(2);
+		this._scrollTop = vp.scrollTop;
+		this._scrollLeft = vp.scrollLeft;
+		const after = this.#windowRows(2);
+		if (before.start !== after.start || before.end !== after.end) this.requestUpdate();
+		return reachedY && reachedX;
+	}
 	/** Height of the row area: the viewport minus the sticky header row inside it. */
 	#bodyHeight() {
 		return this._viewportEl.clientHeight - (this._headerRowEl?.offsetHeight ?? 0);
@@ -2013,6 +2399,7 @@ let DataGridElement = class DataGridElement extends LitElement {
 				const v = value ?? ``;
 				this.groupBy = v || null;
 				this._collapsedGroups = /* @__PURE__ */ new Set();
+				this.#viewState.notify();
 				this.dispatchEvent(new CustomEvent(`datagrid-group-change`, {
 					detail: { groupBy: this.groupBy },
 					bubbles: true,