@ixfx/components 0.15.5 → 0.16.1

package/dist/{data-grid-D7qzmMMp.d.ts → data-grid-Csh5EJW9.d.ts}

@@ -1,7 +1,9 @@
 import "./icon-CDGprSdE.js";
-import { B as ListNativeDragStartEvent, I as ListDragPreviewRenderer, L as ListDragPreviewSourceResolver } from "./tree-component-C6UHO-w9.js";
+import { L as ListDragPreviewRenderer, R as ListDragPreviewSourceResolver, V as ListNativeDragStartEvent } from "./tree-component-DgfkxmVY.js";
+import { a as ViewStateBase, t as GetViewStateOptions } from "./types-LU1u0CB8.js";
+import "./index-9ttcdwlL.js";
 import { n as ListViewportChangeEvent, t as ListViewportChangeDetail } from "./list-viewport-types-BRZsLcvp.js";
-import { S as ListSearchController } from "./index-KN2MW_xD.js";
+import { S as ListSearchController } from "./index-CUErGhCg.js";
 import "./index-DxyyVqzA.js";
 import "./pan-text-CoYmt2qd.js";
 import { LitElement } from "lit";
@@ -99,6 +101,31 @@ type DataGridGroupLabel = (groupKey: string, rows: readonly unknown[]) => string
 /** Whether the data-grid renders its built-in header column/group menu. */
 type DataGridColumnMenu = `auto` | `none`;
 //#endregion
+//#region src/data-grid/data-grid-view-state.d.ts
+/**
+ * Pure view-state helpers for `ixfx-data-grid`. The grid runs these whenever
+ * its rows or columns change, so state keyed to rows / columns that left the
+ * data goes pending and comes back when those keys reappear.
+ */
+/** Saved layout for one column, keyed by column key in {@link DataGridViewState.columns}. */
+type DataGridColumnViewState = {
+  readonly width?: number;
+  readonly visible?: boolean;
+  /** Rank among the saved columns (lower is further left). */
+  readonly order?: number;
+};
+/**
+ * `ixfx-data-grid` view state. `expanded` is keyed by group key; groups
+ * default to open, so a collapsed group is `false`.
+ */
+type DataGridViewState = ViewStateBase & {
+  readonly columns?: Readonly<Record<string, DataGridColumnViewState>>;
+  /** Sorted column + direction; `null` means unsorted. */
+  readonly sort?: DataGridSortState;
+  /** Group-by column key (`null` = ungrouped). Only recorded when `allowGrouping` is on. */
+  readonly groupBy?: string | null;
+};
+//#endregion
 //#region src/data-grid/data-grid.d.ts
 type DataGridSortDetail = {
   readonly sort: DataGridSortState;
@@ -214,8 +241,17 @@ declare class DataGridElement extends LitElement {
    * view and navigation.
    */
   filterPredicate?: (row: unknown) => boolean;
-  /** Text a row is matched against by incremental search. Default: its visible cells joined by a space. */
+  /**
+   * Text a row is matched against by incremental search. Overrides
+   * `searchColumn`; matches against it aren't highlighted, since they can't be
+   * mapped onto a cell.
+   */
   rowSearchText?: (row: unknown) => string;
+  /**
+   * Key of the column incremental search matches against, using the cell's
+   * displayed (formatted) text. Default: the first visible column.
+   */
+  searchColumn: string;
   /**
    * Space-separated subset of `navigate select filter` — limits which
    * incremental-search modes are offered. Unset ⇒ all three; empty ⇒ search
@@ -376,6 +412,21 @@ declare class DataGridElement extends LitElement {
   autoSizeColumn(key: string): boolean;
   private _columnResizeAnimationMs;
   private _onResizePointerDown;
+  /**
+   * 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?: GetViewStateOptions<DataGridViewState>): DataGridViewState;
+  /**
+   * 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: Partial<DataGridViewState>): void;
+  clearPendingViewState(): void;
   getVisibleRange(): {
     startRow: number;
     endRow: number;
@@ -398,4 +449,4 @@ interface DataGridElement {
   removeEventListener: (<K extends keyof DataGridElementEventMap>(type: K, listener: (this: DataGridElement, event: DataGridElementEventMap[K]) => void, options?: boolean | EventListenerOptions) => void) & ((type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions) => void);
 }
 //#endregion
-export { DataGridEditorFactory as A, GlobalFormatter as B, BuiltInFormatterName as C, DataGridDataType as D, DataGridColumnMenu as E, DataGridInteractionMode as F, DataGridRowLook as I, DataGridSelectionMode as L, DataGridGetRowKey as M, DataGridGroupBy as N, DataGridEditability as O, DataGridGroupLabel as P, DataGridSortDirection as R, DataGridViewportChangeEvent as S, DataGridColumn as T, DataGridSelectDetail as _, DataGridColumnReorderDetail as a, DataGridSortEvent as b, DataGridColumnResizeEvent as c, DataGridElement as d, DataGridElementEventMap as f, DataGridRowActivateEvent as g, DataGridRowActivateDetail as h, DataGridCellEditEvent as i, DataGridEditorType as j, DataGridEditorContext as k, DataGridColumnVisibilityDetail as l, DataGridGroupChangeEvent as m, DataGridCellClickEvent as n, DataGridColumnReorderEvent as o, DataGridGroupChangeDetail as p, DataGridCellEditDetail as r, DataGridColumnResizeDetail as s, DataGridCellClickDetail as t, DataGridColumnVisibilityEvent as u, DataGridSelectEvent as v, BuiltInFormatterOptions as w, DataGridViewportChangeDetail as x, DataGridSortDetail as y, DataGridSortState as z };
+export { DataGridEditability as A, DataGridSortDirection as B, DataGridColumnViewState as C, DataGridColumn as D, BuiltInFormatterOptions as E, DataGridGroupBy as F, GlobalFormatter as H, DataGridGroupLabel as I, DataGridInteractionMode as L, DataGridEditorFactory as M, DataGridEditorType as N, DataGridColumnMenu as O, DataGridGetRowKey as P, DataGridRowLook as R, DataGridViewportChangeEvent as S, BuiltInFormatterName as T, DataGridSortState as V, DataGridSelectDetail as _, DataGridColumnReorderDetail as a, DataGridSortEvent as b, DataGridColumnResizeEvent as c, DataGridElement as d, DataGridElementEventMap as f, DataGridRowActivateEvent as g, DataGridRowActivateDetail as h, DataGridCellEditEvent as i, DataGridEditorContext as j, DataGridDataType as k, DataGridColumnVisibilityDetail as l, DataGridGroupChangeEvent as m, DataGridCellClickEvent as n, DataGridColumnReorderEvent as o, DataGridGroupChangeDetail as p, DataGridCellEditDetail as r, DataGridColumnResizeDetail as s, DataGridCellClickDetail as t, DataGridColumnVisibilityEvent as u, DataGridSelectEvent as v, DataGridViewState as w, DataGridViewportChangeDetail as x, DataGridSortDetail as y, DataGridSelectionMode as z };

package/dist/data-grid.d.ts

@@ -1,3 +1,3 @@
-import { B as ListNativeDragStartEvent, F as ListDragPreviewContext, I as ListDragPreviewRenderer, N as ListDragEntry, P as ListDragPreview, R as ListDragSource, z as ListNativeDragStartDetail } from "./tree-component-C6UHO-w9.js";
-import { A as DataGridEditorFactory, B as GlobalFormatter, C as BuiltInFormatterName, D as DataGridDataType, E as DataGridColumnMenu, F as DataGridInteractionMode, I as DataGridRowLook, L as DataGridSelectionMode, M as DataGridGetRowKey, N as DataGridGroupBy, O as DataGridEditability, P as DataGridGroupLabel, R as DataGridSortDirection, S as DataGridViewportChangeEvent, T as DataGridColumn, _ as DataGridSelectDetail, a as DataGridColumnReorderDetail, b as DataGridSortEvent, c as DataGridColumnResizeEvent, d as DataGridElement, f as DataGridElementEventMap, g as DataGridRowActivateEvent, h as DataGridRowActivateDetail, i as DataGridCellEditEvent, j as DataGridEditorType, k as DataGridEditorContext, l as DataGridColumnVisibilityDetail, m as DataGridGroupChangeEvent, n as DataGridCellClickEvent, o as DataGridColumnReorderEvent, p as DataGridGroupChangeDetail, r as DataGridCellEditDetail, s as DataGridColumnResizeDetail, t as DataGridCellClickDetail, u as DataGridColumnVisibilityEvent, v as DataGridSelectEvent, w as BuiltInFormatterOptions, x as DataGridViewportChangeDetail, y as DataGridSortDetail, z as DataGridSortState } from "./data-grid-D7qzmMMp.js";
-export { type BuiltInFormatterName, type BuiltInFormatterOptions, DataGridCellClickDetail, DataGridCellClickEvent, DataGridCellEditDetail, DataGridCellEditEvent, type DataGridColumn, type DataGridColumnMenu, DataGridColumnReorderDetail, DataGridColumnReorderEvent, DataGridColumnResizeDetail, DataGridColumnResizeEvent, DataGridColumnVisibilityDetail, DataGridColumnVisibilityEvent, type DataGridDataType, type DataGridEditability, type DataGridEditorContext, type DataGridEditorFactory, type DataGridEditorType, DataGridElement, DataGridElementEventMap, type DataGridGetRowKey, type DataGridGroupBy, DataGridGroupChangeDetail, DataGridGroupChangeEvent, type DataGridGroupLabel, type DataGridInteractionMode, DataGridRowActivateDetail, DataGridRowActivateEvent, type DataGridRowLook, DataGridSelectDetail, DataGridSelectEvent, type DataGridSelectionMode, DataGridSortDetail, type DataGridSortDirection, DataGridSortEvent, type DataGridSortState, DataGridViewportChangeDetail, DataGridViewportChangeEvent, type GlobalFormatter, type ListDragEntry, type ListDragPreview, type ListDragPreviewContext, type ListDragPreviewRenderer, type ListDragSource, type ListNativeDragStartDetail, type ListNativeDragStartEvent };
+import { B as ListNativeDragStartDetail, F as ListDragPreview, I as ListDragPreviewContext, L as ListDragPreviewRenderer, P as ListDragEntry, V as ListNativeDragStartEvent, z as ListDragSource } from "./tree-component-DgfkxmVY.js";
+import { A as DataGridEditability, B as DataGridSortDirection, C as DataGridColumnViewState, D as DataGridColumn, E as BuiltInFormatterOptions, F as DataGridGroupBy, H as GlobalFormatter, I as DataGridGroupLabel, L as DataGridInteractionMode, M as DataGridEditorFactory, N as DataGridEditorType, O as DataGridColumnMenu, P as DataGridGetRowKey, R as DataGridRowLook, S as DataGridViewportChangeEvent, T as BuiltInFormatterName, V as DataGridSortState, _ as DataGridSelectDetail, a as DataGridColumnReorderDetail, b as DataGridSortEvent, c as DataGridColumnResizeEvent, d as DataGridElement, f as DataGridElementEventMap, g as DataGridRowActivateEvent, h as DataGridRowActivateDetail, i as DataGridCellEditEvent, j as DataGridEditorContext, k as DataGridDataType, l as DataGridColumnVisibilityDetail, m as DataGridGroupChangeEvent, n as DataGridCellClickEvent, o as DataGridColumnReorderEvent, p as DataGridGroupChangeDetail, r as DataGridCellEditDetail, s as DataGridColumnResizeDetail, t as DataGridCellClickDetail, u as DataGridColumnVisibilityEvent, v as DataGridSelectEvent, w as DataGridViewState, x as DataGridViewportChangeDetail, y as DataGridSortDetail, z as DataGridSelectionMode } from "./data-grid-Csh5EJW9.js";
+export { type BuiltInFormatterName, type BuiltInFormatterOptions, DataGridCellClickDetail, DataGridCellClickEvent, DataGridCellEditDetail, DataGridCellEditEvent, type DataGridColumn, type DataGridColumnMenu, DataGridColumnReorderDetail, DataGridColumnReorderEvent, DataGridColumnResizeDetail, DataGridColumnResizeEvent, type DataGridColumnViewState, DataGridColumnVisibilityDetail, DataGridColumnVisibilityEvent, type DataGridDataType, type DataGridEditability, type DataGridEditorContext, type DataGridEditorFactory, type DataGridEditorType, DataGridElement, DataGridElementEventMap, type DataGridGetRowKey, type DataGridGroupBy, DataGridGroupChangeDetail, DataGridGroupChangeEvent, type DataGridGroupLabel, type DataGridInteractionMode, DataGridRowActivateDetail, DataGridRowActivateEvent, type DataGridRowLook, DataGridSelectDetail, DataGridSelectEvent, type DataGridSelectionMode, DataGridSortDetail, type DataGridSortDirection, DataGridSortEvent, type DataGridSortState, type DataGridViewState, DataGridViewportChangeDetail, DataGridViewportChangeEvent, type GlobalFormatter, type ListDragEntry, type ListDragPreview, type ListDragPreviewContext, type ListDragPreviewRenderer, type ListDragSource, type ListNativeDragStartDetail, type ListNativeDragStartEvent };

package/dist/data-grid.js

@@ -1,2 +1,2 @@
-import { t as DataGridElement } from "./data-grid-C1sZX6n9.js";
+import { t as DataGridElement } from "./data-grid-Cqxuwgbb.js";
 export { DataGridElement };

package/dist/{detail-list-q8bs67BM.js → detail-list-Bo5ze3SN.js}

@@ -3,10 +3,12 @@ import { t as themeFallbacks } from "./fallbacks-DQ_5OsmR.js";
 import { n as safeCustomElement, t as __decorate } from "./decorate-VRK8rslU.js";
 import "./icon-1gpwtPx8.js";
 import { t as DataController } from "./data-controller-DOlmqNKb.js";
-import { c as createElementListSearchAdapter, i as ListSearchController, n as listSearchStyles, o as registerListSearchCommands, r as LIST_SEARCH_MODES, u as keyForElement } from "./incr-search-JIhwB49y.js";
+import { c as createElementListSearchAdapter, i as ListSearchController, n as listSearchStyles, o as registerListSearchCommands, r as LIST_SEARCH_MODES, u as keyForElement } from "./incr-search-CgbL-OlS.js";
 import { a as toGroupKey, r as partitionByGroup } from "./grouping-RYPnHkrS.js";
 import { i as animateListItemOut, r as animateListItemIn, t as ListNativeDragController } from "./list-native-drag-controller-CcXoS0YX.js";
-import { r as ListDragSelectController, t as ListSelectionController } from "./list-selection-controller-BeE70lbB.js";
+import { r as ListDragSelectController, t as ListSelectionController } from "./list-selection-controller-5L0Nj9tR.js";
+import { a as capKeys, d as partitionKeys, l as keysToArray, o as flagsFromRecord } from "./pending-BGidHppL.js";
+import { a as restoreElementScroll, o as scrollToOffset, r as captureElementScroll, 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 "./list-group-header.js";
@@ -130,6 +132,62 @@ function itemsInSpanByOrder(items, origin, start, end) {
 	return items.slice(from, to);
 }
 //#endregion
+//#region src/detail-list/detail-list-view-state.ts
+const DETAIL_LIST_VIEW_STATE_KIND = `detail-list`;
+/**
+* Collapsed group keys as an `expanded` record. Collapsed keys whose group
+* isn't currently present are pending; `includePending` decides whether they
+* are written.
+*/
+function collapsedToRecord(collapsed, present, includePending) {
+	const out = {};
+	for (const key of collapsed) if (includePending || present.has(key)) out[key] = false;
+	return out;
+}
+/** `expanded` record → collapsed group keys (only `false` entries collapse). */
+function collapsedFromRecord(record) {
+	const out = /* @__PURE__ */ new Set();
+	for (const [key, open] of flagsFromRecord(record)) if (!open) out.add(key);
+	return capKeys(out);
+}
+/**
+* The collapsed keys whose group isn't present (pending) — what survives a
+* `groupBy` change: the user's collapses belong to the old grouping, but
+* restored keys that never matched are still waiting for theirs.
+*/
+function pendingCollapsed(collapsed, present) {
+	const { missing } = partitionKeys(collapsed, (key) => present.has(key));
+	return missing;
+}
+/** Key → element over a slice of items (first wins), for O(slice) pending resolution. */
+function indexByKey(items) {
+	const out = /* @__PURE__ */ new Map();
+	for (const el of items) {
+		const key = keyForElement(el);
+		if (key !== void 0 && !out.has(key)) out.set(key, el);
+	}
+	return out;
+}
+/**
+* Snapshot the horizontal scroll of the column flow. `visible` must be the
+* visible items in DOM (= column) order.
+*/
+function captureListScroll(viewport, visible) {
+	return captureElementScroll(viewport, visible, keyForElement, `horizontal`);
+}
+/**
+* Apply a saved scroll. With an anchor, `resolve` must return the anchor item
+* only while it is laid out (present and visible); until then this returns
+* `false` so it is retried. Returns `true` once the position was reached.
+*/
+function applyListScroll(viewport, scroll, resolve) {
+	if (scroll.anchor) {
+		const el = resolve(scroll.anchor.key);
+		return el === void 0 ? false : restoreElementScroll(viewport, el, scroll.anchor.offset, `horizontal`);
+	}
+	return scrollToOffset(viewport, scroll.left ?? 0, `horizontal`);
+}
+//#endregion
 //#region src/detail-list/detail-list.ts
 const ITEM_SELECTOR = `:scope > li`;
 const GROUP_HEADER_ATTR = `data-ixfx-group-header`;
@@ -262,6 +320,10 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this.#groupByChanged = false;
 		this.#providerBuilt = 0;
 		this.#data = new DataController(this);
+		this.#viewState = new ViewStateController(this, {
+			kind: DETAIL_LIST_VIEW_STATE_KIND,
+			capture: () => this.getViewState()
+		});
 		this.selection = new ListSelectionController({
 			getOrderedItems: () => this._getVisibleItems(),
 			isSelectable: (el) => this._isCheckable(el),
@@ -283,6 +345,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 					previous,
 					selectedKeys: this.selection.selectedKeys
 				});
+				this.#viewState.notify();
 			}
 		});
 		this.tickled = new TickledController(this, {
@@ -296,6 +359,8 @@ let DetailListElement = class DetailListElement extends LitElement {
 			},
 			onTickle: (id) => {
 				if (id !== void 0) this._dispatch(`list-tickle`, { item: id });
+				if (!this.#viewState.isRestoring) this.#pendingFocus = void 0;
+				if (this.tickled.inputMode === `keyboard`) this.#viewState.notify();
 			},
 			onStateChange: () => this._syncItemStates(),
 			itemWrap: this.itemWrap,
@@ -372,6 +437,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 			highlightKey: SEARCH_HIGHLIGHT_KEY
 		}) });
 		this.#onListScroll = () => {
+			if (!this.#viewState.pendingScroll) this.#viewState.notify();
 			if (this.#viewportScrollRaf !== 0) return;
 			this.#viewportScrollRaf = requestAnimationFrame(() => {
 				this.#viewportScrollRaf = 0;
@@ -525,6 +591,11 @@ let DetailListElement = class DetailListElement extends LitElement {
 	#groupObserver;
 	#providerBuilt;
 	#data;
+	#viewState;
+	/** Saved cursor key not (yet) present. Pending selection lives in `selection`. */
+	#pendingFocus;
+	/** The pending scroll's anchor item, once it exists. */
+	#scrollAnchorEl;
 	#nativeDragging;
 	#postDragSuppressTimer;
 	#blankItemPressPending;
@@ -639,6 +710,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this.#resizeObserver.observe(this);
 		this.#mutationObserver = new MutationObserver((records) => {
 			this.#processAddedChildren(records);
+			this.#reconcileMutations(records);
 			this.#animateChildMutations(records);
 			this.#scheduleGeometry();
 			this.#scheduleGroups();
@@ -662,6 +734,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this.#searchRegistry ??= createCommandRegistry();
 		this.#syncSearchCommands();
 		this.#scheduleGroups();
+		this.#viewState.observeScrollTarget(this);
 	}
 	/**
 	* Collapse-in items appended to the light DOM (however they got there). A bulk
@@ -726,7 +799,8 @@ let DetailListElement = class DetailListElement extends LitElement {
 	willUpdate(changed) {
 		super.willUpdate(changed);
 		if (changed.has(`groupBy`) && this.hasUpdated) {
-			if (this._collapsedGroups.size > 0) this._collapsedGroups = /* @__PURE__ */ new Set();
+			const keep = pendingCollapsed(this._collapsedGroups, this.#presentGroupKeys());
+			if (keep !== this._collapsedGroups) this._collapsedGroups = keep;
 			this.#groupByChanged = true;
 		}
 	}
@@ -749,8 +823,9 @@ let DetailListElement = class DetailListElement extends LitElement {
 			});
 			return;
 		}
-		const shapeChanged = changed.has(`displayProperty`) || changed.has(`formatter`) || changed.has(`iconProperty`) || changed.has(`iconColorProperty`) || changed.has(`textColorProperty`) || changed.has(`badgeProperty`) || changed.has(`keyProperty`);
+		const shapeChanged = changed.has(`displayProperty`) || changed.has(`formatter`) || changed.has(`searchText`) || changed.has(`iconProperty`) || changed.has(`iconColorProperty`) || changed.has(`textColorProperty`) || changed.has(`badgeProperty`) || changed.has(`keyProperty`);
 		if ((changed.has(`items`) || shapeChanged) && this.provider === void 0 && this.items.length > 0) this.#rebuildFromObjects(this.items, !shapeChanged);
+		else if (shapeChanged && this.provider !== void 0 && this.#builtFromProvider.length > 0) this.#rebuildFromObjects(this.#builtFromProvider);
 		this.#syncFromProvider();
 		if (changed.has(`sort`) || changed.has(`sortBy`) || changed.has(`sortComparator`)) this.#applySort();
 		if (changed.has(`filterPredicate`)) {
@@ -786,6 +861,16 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this.#recomputeGeometry();
 		this.#scheduleViewportChangeEmit();
 	}
+	/**
+	* Rebuild every object-item row, for when something the `formatter` (or
+	* `searchText`) reads has changed but the items themselves haven't —
+	* reassigning the same objects keeps their rows as they are. Assigning a new
+	* `formatter` function has the same effect.
+	*/
+	reformat() {
+		const items = this.provider === void 0 ? this.items : this.#builtFromProvider;
+		if (items.length > 0) this.#rebuildFromObjects(items);
+	}
 	addItem(item, options) {
 		let el;
 		if (typeof item === `string`) {
@@ -799,6 +884,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		if (this.sort !== `none`) this.#applySort();
 		if (this.interactionMode === `checked`) this._syncCheckboxes();
 		this.#scheduleGroups();
+		this.#adoptItems([el]);
 	}
 	/**
 	* Collapse + fade `item` out, then detach it; the rows after it slide up to
@@ -839,6 +925,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		if (this.sort !== `none`) this.#applySort();
 		if (this.interactionMode === `checked`) this._syncCheckboxes();
 		this.#scheduleGroups();
+		this.#adoptItems(items);
 	}
 	/**
 	* Get the source object behind an `<li>` built from an `items` array or
@@ -946,20 +1033,151 @@ let DetailListElement = class DetailListElement extends LitElement {
 			if (wanted(el)) yield el;
 		}
 	}
+	/**
+	* Snapshot selection, collapsed groups, cursor and scroll as plain JSON,
+	* keyed by item / group key. Includes pending state for keys not present.
+	*/
+	getViewState(options) {
+		const withPending = options?.includePending ?? true;
+		const focus = this.tickled.inputMode === `keyboard` ? this.tickledKey : void 0;
+		return this.#viewState.shape({
+			selected: keysToArray(this.selection.selectedKeys, withPending ? this.selection.pendingKeys : []),
+			expanded: collapsedToRecord(this._collapsedGroups, this.#presentGroupKeys(), withPending),
+			focus: focus ?? (withPending ? this.#pendingFocus : void 0),
+			scroll: (withPending ? this.#viewState.pendingScroll : void 0) ?? this.#captureScroll()
+		}, options);
+	}
+	/**
+	* Apply saved view state. Fields present replace the current ones; keys not
+	* in the data are applied as matching items arrive (rebuilds, provider
+	* batches, `addItem`, light-DOM appends).
+	*/
+	setViewState(state) {
+		if (!this.#viewState.accepts(state)) return;
+		const index = indexByKey(this.#allItems());
+		const resolve = (key) => index.get(key);
+		this.#viewState.restoring(() => {
+			if (state.expanded) this.#restoreCollapsed(collapsedFromRecord(state.expanded));
+			if (state.selected) this.selection.restoreKeys(state.selected, resolve);
+			if (state.focus !== void 0) {
+				this.#pendingFocus = state.focus;
+				this.#resolveFocus(resolve);
+			}
+			if (state.scroll) {
+				this.#viewState.pendingScroll = state.scroll;
+				this.#scrollAnchorEl = state.scroll.anchor ? resolve(state.scroll.anchor.key) : void 0;
+				this.#scheduleGeometry();
+			}
+			this.#viewState.notify();
+		});
+	}
+	clearPendingViewState() {
+		this.selection.clearPending();
+		this.#pendingFocus = void 0;
+		this.#viewState.pendingScroll = void 0;
+		this.#scrollAnchorEl = void 0;
+		const present = this.#presentGroupKeys();
+		if ([...this._collapsedGroups].some((key) => !present.has(key))) this._collapsedGroups = new Set([...this._collapsedGroups].filter((key) => present.has(key)));
+	}
+	/** Group keys currently shown (empty while ungrouped). */
+	#presentGroupKeys() {
+		return new Set(this.#groupList.map((g) => g.key));
+	}
+	/** Replace the collapsed set; fires `list-group-toggle` for present groups that change. */
+	#restoreCollapsed(next) {
+		const prev = this._collapsedGroups;
+		this._collapsedGroups = next;
+		for (const { key } of this.#groupList) if (prev.has(key) !== next.has(key)) this._dispatch(`list-group-toggle`, {
+			groupKey: key,
+			collapsed: next.has(key)
+		});
+	}
+	/**
+	* Apply pending state to items that just arrived. Only `items` is searched,
+	* so a provider batch costs O(batch), not O(list).
+	*/
+	#adoptItems(items) {
+		const anchorKey = this.#viewState.pendingScroll?.anchor?.key;
+		if (this.selection.pendingKeys.size === 0 && this.#pendingFocus === void 0 && anchorKey === void 0) return;
+		const index = indexByKey(items);
+		if (index.size === 0) return;
+		const resolve = (key) => index.get(key);
+		this.#viewState.restoring(() => {
+			this.selection.resolvePending(resolve);
+			this.#resolveFocus(resolve);
+		});
+		if (anchorKey !== void 0 && index.has(anchorKey)) this.#scrollAnchorEl = index.get(anchorKey);
+	}
+	/** Light-DOM changes: removed items go pending (silently), added items pick up pending state. */
+	#reconcileMutations(records) {
+		const gone = [];
+		const added = [];
+		const tickled = this.tickled.tickledId;
+		let tickledGone = false;
+		for (const record of records) {
+			for (const node of record.removedNodes) {
+				if (!(node instanceof Element) || node.parentElement === this) continue;
+				if (this.selection.selected.has(node)) gone.push(node);
+				if (node === tickled) tickledGone = true;
+			}
+			for (const node of record.addedNodes) if (node instanceof HTMLLIElement && node.parentElement === this) added.push(node);
+		}
+		if (gone.length > 0 && this.selection.demote(gone)) this._syncItemStates();
+		if (tickledGone && tickled) {
+			const key = keyForElement(tickled);
+			this.#viewState.restoring(() => {
+				if (key !== void 0 && this.tickled.inputMode === `keyboard`) this.#pendingFocus ??= key;
+				this.tickled.setTickled(void 0);
+			});
+		}
+		if (added.length > 0) this.#adoptItems(added);
+	}
+	/** Whether `el` is in the list and laid out (not hidden, filtered or collapsed). */
+	#isLaidOut(el) {
+		return el !== void 0 && el.parentElement === this && this.#isItemVisible(el) && !el.hasAttribute(GROUP_COLLAPSED_ATTR);
+	}
+	#resolveFocus(resolve) {
+		const key = this.#pendingFocus;
+		if (key === void 0) return;
+		const el = resolve(key);
+		if (!this.#isLaidOut(el)) return;
+		this.#pendingFocus = void 0;
+		this.tickled.setInputMode(`keyboard`);
+		this.tickled.setTickled(el);
+	}
+	#captureScroll() {
+		return this._listEl ? captureListScroll(this._listEl, this._getVisibleItems()) : void 0;
+	}
+	/** Try the pending scroll; kept until its anchor is laid out and the columns are wide enough. */
+	#applyPendingScroll() {
+		const viewport = this._listEl;
+		if (!viewport || !this.isConnected || !this.#viewState.pendingScroll) return;
+		this.#viewState.applyPendingScroll((scroll) => applyListScroll(viewport, scroll, () => this.#isLaidOut(this.#scrollAnchorEl) ? this.#scrollAnchorEl : void 0));
+		if (!this.#viewState.pendingScroll) this.#scrollAnchorEl = void 0;
+	}
 	#rebuildFromObjects(items, reuseRows = false) {
 		const keyOf = (el) => el.getAttribute(`data-key`) ?? el.getAttribute(`data-search-label`) ?? null;
-		const previousKeys = new Set([...this.selection.selected].map(keyOf).filter((k) => k !== null));
+		const previous = [...this.selection.selected];
+		const previousKeys = new Set(previous.map(keyOf).filter((k) => k !== null));
 		const anchorKey = this.selection.anchor ? keyOf(this.selection.anchor) : null;
 		if (reuseRows) this.#reconcileObjectRows(items);
 		else this.replaceChildren(...items.map((item, index) => this.#createItemEl(item, index)));
-		if (previousKeys.size > 0 || anchorKey !== null) {
+		if (previous.length > 0 || anchorKey !== null) {
 			const next = [];
+			const matched = /* @__PURE__ */ new Set();
 			let anchor;
 			for (const el of this.querySelectorAll(ITEM_SELECTOR)) {
 				const key = keyOf(el);
-				if (key !== null && previousKeys.has(key)) next.push(el);
+				if (key !== null && previousKeys.has(key)) {
+					next.push(el);
+					matched.add(key);
+				}
 				if (key !== null && key === anchorKey) anchor = el;
 			}
+			this.selection.demote(previous.filter((el) => {
+				const key = keyOf(el);
+				return key === null || !matched.has(key);
+			}));
 			this.selection.seed(next, anchor);
 		}
 		if (this.sort !== `none`) this.#applySort();
@@ -967,6 +1185,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this._syncItemStates();
 		this.#scheduleGeometry();
 		this.#scheduleGroups();
+		this.#adoptItems(this.#allItems());
 	}
 	/**
 	* Update the rows to match `items`, keeping the `<li>` of every object that
@@ -1015,6 +1234,8 @@ let DetailListElement = class DetailListElement extends LitElement {
 			li.appendChild(content);
 			if (textColor !== void 0) li.style.color = textColor;
 		}
+		const searchText = this.searchText?.(item, index);
+		if (searchText !== void 0) li.setAttribute(`data-search-label`, searchText);
 		if (this.keyProperty) {
 			const key = this.#propertyValue(item, this.keyProperty);
 			if (key !== void 0 && key !== null) li.setAttribute(`data-key`, String(key));
@@ -1038,8 +1259,8 @@ let DetailListElement = class DetailListElement extends LitElement {
 		let prefix = 0;
 		while (prefix < this.#builtFromProvider.length && prefix < items.length && this.#builtFromProvider[prefix] === items[prefix]) prefix++;
 		if (prefix === this.#builtFromProvider.length && prefix <= items.length) {
-			const tail = items.slice(prefix);
-			for (const item of tail) this.appendChild(this.#createItemEl(item, this.#providerBuilt++));
+			const tail = items.slice(prefix).map((item) => this.#createItemEl(item, this.#providerBuilt++));
+			for (const li of tail) this.appendChild(li);
 			if (this.sort !== `none`) {
 				cancelAnimationFrame(this.#sortRaf);
 				this.#sortRaf = requestAnimationFrame(() => this.#applySort());
@@ -1048,6 +1269,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 			this._syncItemStates();
 			this.#scheduleGeometry();
 			this.#scheduleGroups();
+			this.#adoptItems(tail);
 		} else {
 			this.#providerBuilt = 0;
 			this.#rebuildFromObjects(items);
@@ -1227,6 +1449,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 			groupKey,
 			collapsed
 		});
+		this.#viewState.notify();
 	}
 	toggleGroup(groupKey) {
 		this.setGroupCollapsed(groupKey, !this._collapsedGroups.has(groupKey));
@@ -1255,6 +1478,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this.#geometryScheduled = true;
 		requestAnimationFrame(() => {
 			this.#geometryScheduled = false;
+			this.#applyPendingScroll();
 			this.#emitViewportChangeIfChanged();
 		});
 	}
@@ -1946,6 +2170,7 @@ __decorate([property({
 	attribute: `display-property`
 })], DetailListElement.prototype, "displayProperty", void 0);
 __decorate([property({ attribute: false })], DetailListElement.prototype, "formatter", void 0);
+__decorate([property({ attribute: false })], DetailListElement.prototype, "searchText", void 0);
 __decorate([property({
 	type: String,
 	attribute: `icon-property`

package/dist/{detail-list-CKIKlszv.d.ts → detail-list-DSZ1DDor.d.ts}

@@ -1,14 +1,31 @@
 import "./icon-CDGprSdE.js";
 import { r as IDataProvider } from "./data-provider-BAn_-oR1.js";
-import { B as ListNativeDragStartEvent, I as ListDragPreviewRenderer, L as ListDragPreviewSourceResolver } from "./tree-component-C6UHO-w9.js";
+import { L as ListDragPreviewRenderer, R as ListDragPreviewSourceResolver, V as ListNativeDragStartEvent } from "./tree-component-DgfkxmVY.js";
+import { a as ViewStateBase, s as ViewStateChangeEvent, t as GetViewStateOptions } from "./types-LU1u0CB8.js";
+import "./index-9ttcdwlL.js";
 import { n as ListViewportChangeEvent } from "./list-viewport-types-BRZsLcvp.js";
-import { S as ListSearchController } from "./index-KN2MW_xD.js";
+import { S as ListSearchController } from "./index-CUErGhCg.js";
 import { a as ListGroupEventMap, o as ListGroupInfo, s as ListGroupLabel } from "./grouping-CUKgmkMm.js";
 import { i as ListInteractionMode, l as ListSelectionMode, r as ListElementEventMap } from "./list-selection-types-PjKdhF-a.js";
-import { n as CustomCheckboxOptions, t as AddItemOptions } from "./vertical-list-D8MksoTp.js";
+import { n as CustomCheckboxOptions, t as AddItemOptions } from "./vertical-list-SAx56U-l.js";
 import "./list-group-header.js";
 import { LitElement, PropertyValues } from "lit";
 import { CommandId, CommandRegistry } from "@clinth/ui-commands";
+//#region src/detail-list/detail-list-view-state.d.ts
+/**
+ * Pure helpers behind `ixfx-detail-list`'s view state (see
+ * `docs/infra-view-state.md`). The component keeps only the wiring.
+ *
+ * - `selected` — selected item keys (in `checked` mode, the checked set:
+ *   `data-checked` is derived from the selection, not stored separately).
+ * - `expanded` — `{ [groupKey]: false }` for collapsed groups. Groups default
+ *   open, so only collapses are recorded; `true` re-opens.
+ * - `focus` — keyboard-cursor key.
+ * - `scroll` — horizontal: `left` plus an anchor on the top item of the first
+ *   visible column.
+ */
+type DetailListViewState = ViewStateBase;
+//#endregion
 //#region src/detail-list/types.d.ts
 /** Sort direction applied to the item columns. */
 type DetailSortMode = `none` | `ascending` | `descending`;
@@ -58,6 +75,13 @@ declare class DetailListElement extends LitElement {
   provider: IDataProvider<void, unknown> | undefined;
   displayProperty: string;
   formatter: DetailFormatter | undefined;
+  /**
+   * Text incremental search matches for an object item. Defaults to the
+   * caption when it is a string (`displayProperty` or a string `formatter`),
+   * else the row's whole text — set this when `formatter` returns a `Node`
+   * carrying more than the name (sublines, sizes, dates).
+   */
+  searchText: ((item: unknown, index: number) => string) | undefined;
   iconProperty: string;
   /**
    * Property on each `items` entry holding a CSS colour for the item's
@@ -141,6 +165,13 @@ declare class DetailListElement extends LitElement {
    * changed by outside forces (e.g. an external font load).
    */
   refreshLayout(): void;
+  /**
+   * Rebuild every object-item row, for when something the `formatter` (or
+   * `searchText`) reads has changed but the items themselves haven't —
+   * reassigning the same objects keeps their rows as they are. Assigning a new
+   * `formatter` function has the same effect.
+   */
+  reformat(): void;
   addItem(item: Element | string, options?: AddItemOptions): void;
   /**
    * Collapse + fade `item` out, then detach it; the rows after it slide up to
@@ -194,6 +225,18 @@ declare class DetailListElement extends LitElement {
   /** Move the cursor to the item with this key and scroll it into view. */
   focusKey(key: string): void;
   selectedFilter(kind: `selected` | `checked` | `either`): Generator<Element>;
+  /**
+   * Snapshot selection, collapsed groups, cursor and scroll as plain JSON,
+   * keyed by item / group key. Includes pending state for keys not present.
+   */
+  getViewState(options?: GetViewStateOptions<DetailListViewState>): DetailListViewState;
+  /**
+   * Apply saved view state. Fields present replace the current ones; keys not
+   * in the data are applied as matching items arrive (rebuilds, provider
+   * batches, `addItem`, light-DOM appends).
+   */
+  setViewState(state: Partial<DetailListViewState>): void;
+  clearPendingViewState(): void;
   /** Groups in display order (empty when ungrouped). */
   get groups(): readonly ListGroupInfo[];
   /** Collapse or expand one group. Fires `list-group-toggle` when the state changes. */
@@ -258,6 +301,7 @@ declare global {
 interface DetailListElementEventMap extends ListElementEventMap, ListGroupEventMap {
   'detail-list-viewport-change': ListViewportChangeEvent;
   'list-native-drag-start': ListNativeDragStartEvent<Element>;
+  'view-state-change': ViewStateChangeEvent<DetailListViewState>;
 }
 //#endregion
-export { DetailSortComparator as a, DetailGroupBy as i, DetailListElementEventMap as n, DetailSortItem as o, DetailFormatter as r, DetailSortMode as s, DetailListElement as t };
+export { DetailSortComparator as a, DetailListViewState as c, DetailGroupBy as i, DetailListElementEventMap as n, DetailSortItem as o, DetailFormatter as r, DetailSortMode as s, DetailListElement as t };

package/dist/detail-list.d.ts

@@ -1,6 +1,6 @@
-import { B as ListNativeDragStartEvent, F as ListDragPreviewContext, I as ListDragPreviewRenderer, N as ListDragEntry, P as ListDragPreview, R as ListDragSource, z as ListNativeDragStartDetail } from "./tree-component-C6UHO-w9.js";
+import { B as ListNativeDragStartDetail, F as ListDragPreview, I as ListDragPreviewContext, L as ListDragPreviewRenderer, P as ListDragEntry, V as ListNativeDragStartEvent, z as ListDragSource } from "./tree-component-DgfkxmVY.js";
 import { n as ListViewportChangeEvent, t as ListViewportChangeDetail } from "./list-viewport-types-BRZsLcvp.js";
 import { i as ListGroupChangeEvent, l as ListGroupToggleDetail, n as ListGroupBy, o as ListGroupInfo, r as ListGroupChangeDetail, s as ListGroupLabel, u as ListGroupToggleEvent } from "./grouping-CUKgmkMm.js";
-import { n as CustomCheckboxOptions, t as AddItemOptions } from "./vertical-list-D8MksoTp.js";
-import { a as DetailSortComparator, i as DetailGroupBy, n as DetailListElementEventMap, o as DetailSortItem, r as DetailFormatter, s as DetailSortMode, t as DetailListElement } from "./detail-list-CKIKlszv.js";
-export { type AddItemOptions, type CustomCheckboxOptions, type DetailFormatter, type DetailGroupBy, DetailListElement, DetailListElementEventMap, type DetailSortComparator, type DetailSortItem, type DetailSortMode, type ListDragEntry, type ListDragPreview, type ListDragPreviewContext, type ListDragPreviewRenderer, type ListDragSource, type ListGroupBy, type ListGroupChangeDetail, type ListGroupChangeEvent, type ListGroupInfo, type ListGroupLabel, type ListGroupToggleDetail, type ListGroupToggleEvent, type ListNativeDragStartDetail, type ListNativeDragStartEvent, type ListViewportChangeDetail, type ListViewportChangeEvent };
+import { a as DetailSortComparator, c as DetailListViewState, i as DetailGroupBy, n as DetailListElementEventMap, o as DetailSortItem, r as DetailFormatter, s as DetailSortMode, t as DetailListElement } from "./detail-list-DSZ1DDor.js";
+import { n as CustomCheckboxOptions, t as AddItemOptions } from "./vertical-list-SAx56U-l.js";
+export { type AddItemOptions, type CustomCheckboxOptions, type DetailFormatter, type DetailGroupBy, DetailListElement, DetailListElementEventMap, type DetailListViewState, type DetailSortComparator, type DetailSortItem, type DetailSortMode, type ListDragEntry, type ListDragPreview, type ListDragPreviewContext, type ListDragPreviewRenderer, type ListDragSource, type ListGroupBy, type ListGroupChangeDetail, type ListGroupChangeEvent, type ListGroupInfo, type ListGroupLabel, type ListGroupToggleDetail, type ListGroupToggleEvent, type ListNativeDragStartDetail, type ListNativeDragStartEvent, type ListViewportChangeDetail, type ListViewportChangeEvent };

package/dist/detail-list.js

@@ -1,3 +1,3 @@
-import { t as DetailListElement } from "./detail-list-q8bs67BM.js";
+import { t as DetailListElement } from "./detail-list-Bo5ze3SN.js";
 import "./list-group-header.js";
 export { DetailListElement };