@ixfx/components 0.15.5 → 0.16.0

package/dist/vertical-list-1V1Vg2O5.js

@@ -0,0 +1,1993 @@
+import { t as TickledController } from "./tickled-controller-D-HZymaZ.js";
+import { t as themeFallbacks } from "./fallbacks-DQ_5OsmR.js";
+import { n as safeCustomElement, t as __decorate } from "./decorate-VRK8rslU.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 { 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-5L0Nj9tR.js";
+import { l as keysToArray } from "./pending-BGidHppL.js";
+import { a as restoreElementScroll, n as anchorFromRow, 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 "./editable-label.js";
+import { LitElement, css, html, render } from "lit";
+import { property } from "lit/decorators.js";
+import { createCommandRegistry } from "@clinth/ui-commands";
+import { ifDefined } from "lit/directives/if-defined.js";
+//#region src/vertical-list/vertical-list-view-state.ts
+/** Key → row over `rows`. Keyless rows are skipped; the first row with a key wins. */
+function indexByKey(rows, getKey) {
+	const out = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const key = getKey(row);
+		if (key !== void 0 && !out.has(key)) out.set(key, row);
+	}
+	return out;
+}
+/** Items of `selected` that `isPresent` reports have left the list. */
+function departed(selected, isPresent) {
+	const out = [];
+	for (const item of selected) if (!isPresent(item)) out.push(item);
+	return out;
+}
+/**
+* Carry a selection across a rebuild that replaced every row element: each
+* previously-selected row maps to the new row with the same key, or is listed
+* in `gone` so its key can be kept pending.
+*/
+function rekeySelection(previous, anchorKey, rows, getKey) {
+	const previousByKey = /* @__PURE__ */ new Map();
+	const gone = [];
+	for (const el of previous) {
+		const key = getKey(el);
+		if (key === void 0) gone.push(el);
+		else previousByKey.set(key, el);
+	}
+	const live = [];
+	const matched = /* @__PURE__ */ new Set();
+	let anchor;
+	for (const row of rows) {
+		const key = getKey(row);
+		if (key === void 0) continue;
+		if (previousByKey.has(key) && !matched.has(key)) {
+			live.push(row);
+			matched.add(key);
+		}
+		if (key === anchorKey) anchor ??= row;
+	}
+	for (const [key, el] of previousByKey) if (!matched.has(key)) gone.push(el);
+	return {
+		live,
+		gone,
+		anchor
+	};
+}
+/**
+* - a keyboard cursor whose row left the list (`departedKey`) goes pending,
+*   unless something is already pending
+* - a pending key that now resolves is applied
+*/
+function reconcileFocus(pending, departedKey, has) {
+	const next = pending ?? departedKey;
+	if (next !== void 0 && has(next)) return {
+		pending: void 0,
+		apply: next
+	};
+	return {
+		pending: next,
+		apply: void 0
+	};
+}
+/** Anchor for a virtualised list with fixed `stride` rows. */
+function captureVirtualScroll(top, stride, count, keyAt) {
+	if (stride <= 0 || count === 0) return anchorFromRow(top, void 0, 0);
+	const index = Math.min(count - 1, Math.max(0, Math.floor(top / stride)));
+	return anchorFromRow(top, keyAt(index), index * stride);
+}
+/**
+* Scroll offset a saved state asks for in a virtualised list, or `undefined`
+* while its anchor key isn't in the list yet.
+*/
+function virtualScrollTarget(scroll, stride, indexOf) {
+	if (!scroll.anchor) return scroll.top;
+	const index = indexOf(scroll.anchor.key);
+	return index < 0 ? void 0 : index * stride + scroll.anchor.offset;
+}
+//#endregion
+//#region src/vertical-list/vertical-list.ts
+const ITEM_SELECTOR = `li:not([data-virtual-spacer]), [data-list-item]:not([data-virtual-spacer])`;
+/**
+* Rows rendered above/below the viewport as scroll margin. Grid-list uses 2;
+* vertical rows are shorter relative to the viewport, so 3.
+*/
+const VIRTUAL_OVERSCAN = 3;
+/**
+* Layout for the per-item icon / badge wrappers `#decorateAdapterItem` adds.
+*
+* Applied as inline `cssText` rather than shadow CSS because `::slotted()` only
+* matches the host's *direct* children — these spans live inside a slotted
+* `<li>`, so a `::slotted()` rule could never reach them. The values still read
+* the CSS custom properties, so they stay themeable from the outside.
+*/
+const ITEM_ICON_EL_CSS = `flex:none;display:inline-flex;align-items:center;justify-content:center;overflow:hidden;margin-inline-end:var(--list-item-icon-gap,6px);width:var(--list-item-icon-size,1em);height:var(--list-item-icon-size,1em)`;
+const ITEM_BADGE_EL_CSS = `flex:none;display:inline-flex;align-items:center;margin-inline-start:auto;padding-inline-start:var(--list-item-badge-gap,8px)`;
+/** 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;
+}
+let VerticalListElement = class VerticalListElement extends LitElement {
+	constructor(..._args) {
+		super(..._args);
+		this.selectionMode = `single`;
+		this.interactionMode = `standard`;
+		this.itemWrap = `stop`;
+		this.itemsDraggable = false;
+		this.keyProperty = ``;
+		this.virtualize = false;
+		this.itemHeight = 0;
+		this.itemsDroppable = false;
+		this.#customWrappers = /* @__PURE__ */ new Map();
+		this.#wrappedElements = /* @__PURE__ */ new Set();
+		this.#itemData = /* @__PURE__ */ new WeakMap();
+		this.#animatedItems = /* @__PURE__ */ new WeakSet();
+		this.#allItems = [];
+		this.#pool = document.createDocumentFragment();
+		this.#windowStart = 0;
+		this.#windowEnd = 0;
+		this.#pendingAnimate = [];
+		this.#suspendAdapterRebuild = false;
+		this.#scrollRaf = 0;
+		this.#lastViewportH = 0;
+		this.#virtualWarned = false;
+		this.#viewState = new ViewStateController(this, {
+			kind: `vertical-list`,
+			capture: () => this.getViewState()
+		});
+		this.#reconcilingViewState = false;
+		this.selection = new ListSelectionController({
+			getOrderedItems: () => this.#selectionOrder(),
+			isSelectable: (el) => this._isCheckable(el),
+			getModes: () => ({
+				selectionMode: this.selectionMode,
+				interactionMode: this.interactionMode
+			}),
+			getKey: keyForElement,
+			onChange: (selected, previous) => {
+				this._syncItemStates();
+				this.#viewState.notify();
+				this._dispatch(`list-select`, {
+					selected,
+					previous,
+					selectedKeys: this.selection.selectedKeys
+				});
+			}
+		});
+		this.tickled = ((self) => new TickledController(self, {
+			getItems: () => self.#selectionOrder().map((el) => ({
+				id: el,
+				enabled: !el.hasAttribute(`not-checked`)
+			})),
+			onTickle: (id) => {
+				if (self.tickled.inputMode === `keyboard`) {
+					if (!self.#viewState.isRestoring) self.#pendingFocus = void 0;
+					self.#viewState.notify();
+				}
+				if (id !== void 0) this._dispatch(`list-tickle`, { item: id });
+			},
+			onStateChange: () => this._syncItemStates(),
+			get itemWrap() {
+				return self.itemWrap;
+			},
+			hoverDisabled: () => this.#dragSelect.isDragging || this.#nativeDrag.isDragging
+		}))(this);
+		this.#nativeDragging = false;
+		this.#postDragSuppressTimer = 0;
+		this.#nativeDrag = new ListNativeDragController(this, {
+			source: `vertical-list`,
+			isEnabled: () => this.itemsDraggable && this.selectionMode !== `none` && this._getVisibleItems().length > 0,
+			resolveEventToKey: (target) => {
+				if (!(target instanceof Element)) return void 0;
+				const item = target.closest?.(ITEM_SELECTOR);
+				if (!item || !this.contains(item) || this.#wrappedElements.has(item)) return void 0;
+				return keyForElement(item);
+			},
+			prepareSelection: (originKey) => this.#prepareNativeDrag(originKey),
+			getMetrics: () => ({}),
+			getRenderer: () => this.dragPreviewRenderer,
+			getDragPreviewSourceResolver: () => this.dragPreviewSource,
+			dispatch: (detail) => this._dispatchCancelable(`list-native-drag-start`, detail),
+			onActiveChange: (active, originKey) => {
+				this.#nativeDragging = active;
+				this.toggleAttribute(`data-native-dragging`, active);
+				for (const el of this._getVisibleItems()) el.toggleAttribute(`data-drag-origin`, active && originKey !== void 0 && keyForElement(el) === originKey);
+				if (active) {
+					const count = this.selection.selected.size;
+					this.setAttribute(`aria-label`, count <= 1 ? `Dragging 1 item` : `Dragging ${count} items`);
+				} else this.removeAttribute(`aria-label`);
+				this.requestUpdate();
+			},
+			onEnd: () => {
+				this.#nativeDragging = false;
+				this.toggleAttribute(`data-native-dragging`, false);
+				this.removeAttribute(`aria-label`);
+				for (const el of this._getVisibleItems()) el.removeAttribute(`data-drag-origin`);
+				if (this.#virtualActive()) for (const el of this.#allItems) el.removeAttribute(`data-drag-origin`);
+				this.#startPostDragSuppressTimer();
+			},
+			syncLightDomDraggable: () => this._syncNativeDraggable()
+		});
+		this.#dragSelect = new ListDragSelectController(this, {
+			getSurface: () => this.renderRoot.querySelector(`.container`),
+			isEnabled: () => !this.#virtualActive() && this.selection.canDragSelect() && this._getVisibleItems().length > 0 && !this.hasAttribute(`disable-drag-select`),
+			hitTest: (rect) => this.#marqueeHitTest(rect),
+			getBaseSelection: () => this.selection.selected,
+			onPreview: (preview, rect) => {
+				this.#marqueeRect = rect;
+				for (const el of this._getVisibleItems()) el.toggleAttribute(`data-marquee`, preview.has(el));
+				this.requestUpdate();
+			},
+			onCommit: (finalSet) => {
+				this.selection.applyDragSelection(finalSet);
+				for (const el of this._getVisibleItems()) el.removeAttribute(`data-marquee`);
+				this.#marqueeRect = void 0;
+				this.requestUpdate();
+			},
+			autoScroll: (_dx, dy) => {
+				const list = this.renderRoot.querySelector(`ul`);
+				if (list) list.scrollTop += dy;
+			}
+		});
+		this.search = new ListSearchController(this, { adapter: createElementListSearchAdapter(this, {
+			itemSelector: ITEM_SELECTOR,
+			getLabel: (el) => el.getAttribute(`data-search-label`) ?? el.textContent?.trim() ?? ``,
+			highlightKey: `vertical-list-search`,
+			getAllItems: () => this.#selectionOrder(),
+			observeContainer: false
+		}) });
+		this.#onScroll = () => {
+			if (!this.#viewState.pendingScroll) this.#viewState.notify();
+			if (this.#scrollRaf !== 0) return;
+			this.#scrollRaf = requestAnimationFrame(() => {
+				this.#scrollRaf = 0;
+				this.#syncVirtualWindow();
+				this.#emitViewportChangeIfChanged();
+			});
+		};
+		this._onPointerOver = (e) => {
+			const item = this._findListItem(e.composedPath());
+			if (item) this.tickled.handlePointerEnter(item);
+		};
+		this._onPointerLeave = (e) => {
+			this.tickled.handlePointerLeave(e);
+		};
+		this._onKeyDown = (e) => {
+			if (this.search.isOpen || this.#isEditEvent(e)) return;
+			if (e.key === `ContextMenu` || e.shiftKey && e.key === `F10`) {
+				const id = this.tickled.tickledId;
+				if (id) {
+					e.preventDefault();
+					const rect = id.getBoundingClientRect();
+					this.#requestContextMenu(id, rect.left, rect.bottom);
+				}
+				return;
+			}
+			if ((e.ctrlKey || e.metaKey) && e.key === `a`) {
+				if (this.selection.canSelectAll()) {
+					e.preventDefault();
+					this.selection.selectAll();
+				}
+				return;
+			}
+			switch (e.key) {
+				case `ArrowDown`:
+					e.preventDefault();
+					this.tickled.handleKeyboardNavigation(`next`);
+					this.#revealCursor();
+					if (e.shiftKey && this.interactionMode === `vscode`) {
+						const cur = this.tickled.tickledId;
+						if (cur) this.selection.rangeTo(cur);
+					}
+					break;
+				case `ArrowUp`:
+					e.preventDefault();
+					this.tickled.handleKeyboardNavigation(`previous`);
+					this.#revealCursor();
+					if (e.shiftKey && this.interactionMode === `vscode`) {
+						const cur = this.tickled.tickledId;
+						if (cur) this.selection.rangeTo(cur);
+					}
+					break;
+				case `Home`:
+					e.preventDefault();
+					this.tickled.handleKeyboardNavigation(`first`);
+					this.#revealCursor();
+					break;
+				case `End`:
+					e.preventDefault();
+					this.tickled.handleKeyboardNavigation(`last`);
+					this.#revealCursor();
+					break;
+				case `PageDown`:
+					e.preventDefault();
+					this.#handlePage(1);
+					break;
+				case `PageUp`:
+					e.preventDefault();
+					this.#handlePage(-1);
+					break;
+				case `Enter`: {
+					const id = this.tickled.tickledId;
+					if (id) {
+						e.preventDefault();
+						this._dispatch(`list-item-click`, { item: id });
+						this._activateItem(id);
+					}
+					break;
+				}
+				case ` `: {
+					const id = this.tickled.tickledId;
+					if (id) {
+						e.preventDefault();
+						this.selection.handleSpace(id);
+					}
+					break;
+				}
+				case `Escape`: this.selection.clear();
+			}
+		};
+		this._onClick = (e) => {
+			if (this.#isEditEvent(e)) return;
+			if (this.#dragSelect.isDragging || this.#nativeDrag.isDragging || this.#postDragSuppressTimer !== 0) return;
+			const item = this._findListItem(e.composedPath());
+			if (!item) return;
+			this._dispatch(`list-item-click`, { item });
+			this.selection.handleClick(item, e);
+		};
+		this._onDblClick = (e) => {
+			if (this.#isEditEvent(e)) return;
+			const item = this._findListItem(e.composedPath());
+			if (item) this._activateItem(item);
+		};
+		this._onDragOver = (e) => {
+			const dt = e.dataTransfer;
+			if (!this.itemsDroppable || !dt || this.#isEditEvent(e)) return;
+			const item = this._findListItem(e.composedPath());
+			if (this.canDrop && !this.canDrop(item, dt)) {
+				this.#clearDropTarget();
+				return;
+			}
+			if (this.#dragOver && this.#dragOver.item !== item) this.#clearDropTarget();
+			this.#dragOver = { item };
+			if (!!this._dispatchCancelable(`list-drag-over`, {
+				key: item ? keyForElement(item) : void 0,
+				item,
+				dataTransfer: dt
+			})) {
+				this.#highlightDropTarget(void 0, false);
+				return;
+			}
+			e.preventDefault();
+			if (dt.dropEffect === `none`) dt.dropEffect = `copy`;
+			this.#highlightDropTarget(item, true);
+		};
+		this._onDragLeave = (e) => {
+			const next = e.relatedTarget;
+			if (next instanceof Node && this.contains(next)) return;
+			this.#clearDropTarget();
+		};
+		this._onDrop = (e) => {
+			const dt = e.dataTransfer;
+			if (!this.itemsDroppable || !dt || this.#isEditEvent(e)) return;
+			const item = this._findListItem(e.composedPath());
+			if (this.canDrop && !this.canDrop(item, dt)) {
+				this.#clearDropTarget();
+				return;
+			}
+			e.preventDefault();
+			this.#dragOver = void 0;
+			this.#highlightDropTarget(void 0, false);
+			this._dispatch(`list-drop`, {
+				key: item ? keyForElement(item) : void 0,
+				item,
+				dataTransfer: dt
+			});
+		};
+		this._onContextMenu = (e) => {
+			if (this.#isEditEvent(e)) return;
+			const item = this._findListItem(e.composedPath());
+			if (!item) return;
+			if (!this.#requestContextMenu(item, e.clientX, e.clientY)) e.preventDefault();
+		};
+	}
+	#customWrappers;
+	#wrappedElements;
+	/** Source object behind each adapter-built row (`items` mode). */
+	#itemData;
+	/** Watches for items added to the light DOM so they can be animated in. */
+	#itemObserver;
+	/** Items that have already played (or been skipped for) their enter animation. */
+	#animatedItems;
+	/**
+	* Global row order while virtualized — the source of truth both modes
+	* write to. Holds canonical rows (checked-mode wrappers, not inners).
+	* Non-virtualized mode ignores it and reads the DOM directly.
+	*/
+	#allItems;
+	/** Off-DOM pool for recycled offscreen rows. `querySelectorAll` works on it. */
+	#pool;
+	/** Current rendered window as registry indices `[start, end)`. */
+	#windowStart;
+	#windowEnd;
+	/** Window rows queued for their enter animation after placement. */
+	#pendingAnimate;
+	/** Skip one adapter rebuild (updateItem's write-through to `items`). */
+	#suspendAdapterRebuild;
+	#scrollRaf;
+	#resizeObserver;
+	/** Key sets as of the last viewport-change dispatch, for dedupe. */
+	#lastViewportRenderedKeys;
+	#lastViewportVisibleKeys;
+	#topSpacer;
+	#bottomSpacer;
+	/** Last measured viewport height — kept so a 0 read can't collapse the window. */
+	#lastViewportH;
+	#virtualWarned;
+	#viewState;
+	/** Saved keyboard-cursor key whose row isn't in the list (yet). */
+	#pendingFocus;
+	#reconcilingViewState;
+	#nativeDragging;
+	#postDragSuppressTimer;
+	#nativeDrag;
+	#prepareNativeDrag(originKey) {
+		const originEl = this.#itemForKey(originKey);
+		if (!originEl || !this._isCheckable(originEl)) return void 0;
+		if (!this.selection.selected.has(originEl)) this.selection.replace(originEl);
+		const ordered = this.#selectionOrder();
+		const selected = [];
+		ordered.forEach((el) => {
+			if (!this.selection.selected.has(el)) return;
+			const idx = this.#registryIndexOf(el);
+			selected.push({
+				key: keyForElement(el) ?? originKey,
+				index: idx,
+				item: el,
+				element: el
+			});
+		});
+		const origin = selected.find((entry) => entry.key === originKey);
+		if (!origin) return void 0;
+		return {
+			origin,
+			selected
+		};
+	}
+	_syncNativeDraggable() {
+		if (!this.isConnected) return;
+		for (const el of this.querySelectorAll(ITEM_SELECTOR)) {
+			if (this.#wrappedElements.has(el)) continue;
+			if (el instanceof HTMLElement) el.draggable = this.itemsDraggable && this._isCheckable(el);
+		}
+	}
+	#startPostDragSuppressTimer() {
+		if (this.#postDragSuppressTimer) clearTimeout(this.#postDragSuppressTimer);
+		this.#postDragSuppressTimer = window.setTimeout(() => {
+			this.#postDragSuppressTimer = 0;
+		}, 0);
+	}
+	/** Live drag-select preview rect (surface-relative); the covered items carry `data-marquee`. */
+	#marqueeRect;
+	#dragSelect;
+	/** Collect visible items whose surface-relative box intersects `rect`. */
+	#marqueeHitTest(rect) {
+		const surface = this.renderRoot.querySelector(`.container`);
+		if (!surface) return [];
+		const box = surface.getBoundingClientRect();
+		const rx0 = rect.x;
+		const ry0 = rect.y;
+		const rx1 = rect.x + rect.width;
+		const ry1 = rect.y + rect.height;
+		const out = [];
+		for (const el of this._getVisibleItems()) {
+			const r = el.getBoundingClientRect();
+			const left = r.left - box.left;
+			const top = r.top - box.top;
+			if (left <= rx1 && left + r.width >= rx0 && top <= ry1 && top + r.height >= ry0) out.push(el);
+		}
+		return out;
+	}
+	#marqueeStyle(rect) {
+		return `left:${rect.x}px;top:${rect.y}px;width:${Math.max(0, rect.width)}px;height:${Math.max(0, rect.height)}px`;
+	}
+	#searchRegistry;
+	#unregisterSearchCommands;
+	/** Command registry carrying this list's `list.search.*` commands. */
+	get registry() {
+		return this.#searchRegistry;
+	}
+	#effectiveSearchModes() {
+		const raw = this.searchModes?.trim();
+		let modes;
+		if (raw === void 0) modes = [...LIST_SEARCH_MODES];
+		else {
+			const requested = new Set(raw.split(/\s+/));
+			modes = LIST_SEARCH_MODES.filter((m) => requested.has(m));
+		}
+		return this.#virtualActive() ? modes.filter((m) => m !== `filter`) : modes;
+	}
+	#syncSearchCommands() {
+		if (!this.#searchRegistry) return;
+		this.search.setModes(this.#effectiveSearchModes());
+		this.#unregisterSearchCommands?.();
+		this.#unregisterSearchCommands = registerListSearchCommands(this.#searchRegistry, this.search);
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		if (!this.hasAttribute(`tabindex`)) this.tabIndex = 0;
+		this.addEventListener(`pointerover`, this._onPointerOver);
+		this.addEventListener(`pointerleave`, this._onPointerLeave);
+		this.addEventListener(`keydown`, this._onKeyDown);
+		this.addEventListener(`click`, this._onClick);
+		this.addEventListener(`dblclick`, this._onDblClick);
+		this.addEventListener(`dragover`, this._onDragOver);
+		this.addEventListener(`dragleave`, this._onDragLeave);
+		this.addEventListener(`drop`, this._onDrop);
+		this.addEventListener(`contextmenu`, this._onContextMenu);
+		for (const el of this.querySelectorAll(ITEM_SELECTOR)) this.#animatedItems.add(el);
+		this.#itemObserver ??= new MutationObserver((records) => this.#onItemsMutated(records));
+		this.#itemObserver.observe(this, { childList: true });
+		this.#searchRegistry ??= createCommandRegistry();
+		this.#syncSearchCommands();
+		this.#ensureResizeObserved();
+	}
+	disconnectedCallback() {
+		super.disconnectedCallback();
+		this.removeEventListener(`pointerover`, this._onPointerOver);
+		this.removeEventListener(`pointerleave`, this._onPointerLeave);
+		this.removeEventListener(`keydown`, this._onKeyDown);
+		this.removeEventListener(`click`, this._onClick);
+		this.removeEventListener(`dblclick`, this._onDblClick);
+		this.removeEventListener(`dragover`, this._onDragOver);
+		this.removeEventListener(`dragleave`, this._onDragLeave);
+		this.removeEventListener(`drop`, this._onDrop);
+		this.removeEventListener(`contextmenu`, this._onContextMenu);
+		this.#clearDropTarget();
+		this.#edit = void 0;
+		this.#itemObserver?.disconnect();
+		this.#resizeObserver?.disconnect();
+		this.#resizeObserver = void 0;
+		if (this.#scrollRaf !== 0) {
+			cancelAnimationFrame(this.#scrollRaf);
+			this.#scrollRaf = 0;
+		}
+		this.#unregisterSearchCommands?.();
+		this.#unregisterSearchCommands = void 0;
+		this.#searchRegistry = void 0;
+		if (this.#postDragSuppressTimer) {
+			clearTimeout(this.#postDragSuppressTimer);
+			this.#postDragSuppressTimer = 0;
+		}
+	}
+	/**
+	* The shadow scroll list only exists after the first render; start
+	* watching it so resizes move the window (virtualized) and the visible
+	* set (plain) too.
+	*/
+	firstUpdated() {
+		this.#ensureResizeObserved();
+		this.#viewState.observeScrollTarget(this);
+		this.#reconcileViewState();
+	}
+	/**
+	* Animate in items appended to the light DOM (however they got there —
+	* {@link addItem}, direct `appendChild`, a framework binding). A bulk populate
+	* (roughly everything at once) is left alone, as are the wrapper `<li>`s the
+	* checked-mode plumbing shuffles around.
+	*/
+	#onItemsMutated(records) {
+		if (!this.isConnected) return;
+		if (this.#virtualActive()) {
+			this.#syncVirtualWindow(this.#reconcileRecords(records));
+			this.#scheduleViewportChangeEmit();
+			return;
+		}
+		const fresh = [];
+		for (const record of records) for (const node of record.addedNodes) {
+			if (!(node instanceof HTMLElement) || node.parentElement !== this) continue;
+			if (!node.matches(ITEM_SELECTOR)) continue;
+			if (this.#animatedItems.has(node) || this.#customWrappers.has(node) || this.#wrappedElements.has(node)) continue;
+			this.#animatedItems.add(node);
+			fresh.push(node);
+		}
+		this.#scheduleViewportChangeEmit();
+		if (records.some((r) => r.removedNodes.length > 0)) this.#demoteDeparted(departed(this.selection.selected, (el) => el.parentNode === this || this.#wrappedElements.has(el)));
+		this.#reconcileViewState();
+		if (fresh.length === 0) return;
+		if (this.#isBulkPopulate(fresh.length)) return;
+		for (const el of fresh) animateListItemIn(el);
+	}
+	/**
+	* Whether `freshCount` newly-added rows amount to a bulk populate (first
+	* render / wholesale replace) rather than an incremental add — the single
+	* threshold both the virtual and non-virtual mutation-observer paths use
+	* to decide whether to skip the enter animation.
+	*/
+	#isBulkPopulate(freshCount) {
+		return freshCount >= this.querySelectorAll(ITEM_SELECTOR).length;
+	}
+	updated(changed) {
+		super.updated(changed);
+		if (changed.has(`searchModes`)) this.#syncSearchCommands();
+		if (changed.has(`virtualize`) || changed.has(`itemHeight`)) {
+			const wasActive = (changed.has(`virtualize`) ? changed.get(`virtualize`) : this.virtualize) === true && ((changed.has(`itemHeight`) ? changed.get(`itemHeight`) : this.itemHeight) ?? 0) > 0;
+			if (this.#virtualActive()) {
+				if (!wasActive) {
+					this.#pool = document.createDocumentFragment();
+					this.#allItems = [...this.querySelectorAll(ITEM_SELECTOR)];
+					for (const el of this.#allItems) this.#animatedItems.add(el);
+					this.#pendingAnimate = [];
+				}
+				this.#syncVirtualWindow(true);
+			} else if (wasActive) this.#teardownVirtualWindow();
+			else if (this.virtualize && !this.#virtualWarned) {
+				this.#virtualWarned = true;
+				console.warn(`ixfx-vertical-list: virtualize needs item-height > 0 — running non-virtualized.`);
+			}
+			this.#syncSearchCommands();
+		}
+		if ((changed.has(`items`) || changed.has(`formatter`) || changed.has(`keyProperty`) || changed.has(`icon`) || changed.has(`iconColor`) || changed.has(`textColor`) || changed.has(`badge`)) && this.items !== void 0) {
+			if (this.#suspendAdapterRebuild) this.#suspendAdapterRebuild = false;
+			else if (this.#virtualActive()) this.#rebuildAdapterVirtual();
+			else this.#rebuildFromAdapter();
+		}
+		if (changed.has(`interactionMode`)) {
+			this.selection.clearAnchor();
+			const previousSelected = this.selection.selected;
+			const savedWrappers = changed.get(`interactionMode`) === `checked` ? new Map(this.#customWrappers) : null;
+			this._syncCheckboxes();
+			if (previousSelected.size > 0) {
+				if (savedWrappers && savedWrappers.size > 0) this.selection.remap((el) => savedWrappers.get(el) ?? el);
+				else if (this.#customWrappers.size > 0) {
+					const innerToWrapper = new Map([...this.#customWrappers].map(([w, i]) => [i, w]));
+					this.selection.remap((el) => innerToWrapper.get(el) ?? el);
+				}
+			}
+			this._syncItemStates();
+		} else if (changed.has(`checkboxRenderer`) && this.interactionMode === `checked`) this._syncCheckboxes();
+		if (changed.has(`itemsDraggable`) || changed.has(`interactionMode`)) {
+			this._syncNativeDraggable();
+			this.#nativeDrag.refreshDraggable();
+		}
+	}
+	/** The most recently selected item, or `undefined` if nothing is selected. */
+	get selectedItem() {
+		return [...this.selection.selected].at(-1);
+	}
+	/** The full current selection set (read-only). */
+	get selectedItems() {
+		return this.selection.selected;
+	}
+	addItem(item, options) {
+		let el;
+		if (typeof item === `string`) {
+			const li = document.createElement(`li`);
+			li.textContent = item;
+			el = li;
+		} else el = item;
+		if (options?.notChecked) el.setAttribute(`not-checked`, ``);
+		this.appendChild(el);
+		if (this.#virtualActive()) {
+			this.#syncVirtualWindow(true);
+			return;
+		}
+		if (this.interactionMode === `checked`) this._syncCheckboxes();
+		this.search.refresh();
+		this.#reconcileViewState();
+	}
+	/**
+	* Collapse + fade `item` out, then detach it. The rows below slide up to
+	* close the gap. Resolves once the element has actually been removed.
+	* Under `prefers-reduced-motion: reduce` it's removed immediately.
+	* A pooled (offscreen) row under virtualization is removed immediately.
+	*/
+	removeItem(item) {
+		this.#demoteDeparted([item]);
+		if (this.#virtualActive()) return (item.parentNode !== this ? Object.assign(Promise.resolve(), { animation: void 0 }) : animateListItemOut(item)).then(() => {
+			const idx = this.#registryIndexOf(item);
+			if (idx >= 0) this.#allItems.splice(idx, 1);
+			this.#cleanupWrapperRefs(item);
+			item.remove();
+			if (this.interactionMode === `checked`) this._syncCheckboxes();
+			this.#syncVirtualWindow(true);
+		});
+		return animateListItemOut(item).then(() => {
+			item.remove();
+			if (this.interactionMode === `checked`) this._syncCheckboxes();
+		});
+	}
+	/** {@link removeItem} for several items at once. */
+	removeItems(items) {
+		return Promise.all([...items].map((item) => this.removeItem(item))).then(() => void 0);
+	}
+	clearItems() {
+		this.#customWrappers.clear();
+		if (this.#virtualActive()) {
+			this.#allItems = [];
+			this.#pool = document.createDocumentFragment();
+			this.#pendingAnimate = [];
+		}
+		this.replaceChildren();
+		this.selection.reset();
+		this._syncItemStates();
+		this.search.refresh();
+		if (this.#virtualActive()) this.#syncVirtualWindow(true);
+		else this.#reconcileViewState();
+	}
+	/**
+	* Replace the entire item list in one call.
+	* Equivalent to `clearItems()` followed by `addItem()` for each element.
+	* Preserves `interactionMode` checkbox wrapping.
+	*/
+	setItems(items) {
+		if (this.#virtualActive()) {
+			this.#customWrappers.clear();
+			this.#pool = document.createDocumentFragment();
+			this.#pendingAnimate = [];
+			this.#allItems = [...items];
+			for (const el of this.#allItems) this.#animatedItems.add(el);
+			this.selection.reset();
+			this.search.refresh();
+			this.#syncVirtualWindow(true);
+			return;
+		}
+		for (const item of items) this.appendChild(item);
+		if (this.interactionMode === `checked`) this._syncCheckboxes();
+		this.search.refresh();
+		this.#reconcileViewState();
+	}
+	/**
+	* Dispatch a command to this list — used by `ixfx-grouped-item-lister` to
+	* forward commands to all sub-components. Routes through the command registry
+	* (so `list.search.*` and any other registered commands work).
+	*/
+	dispatch(commandId, args) {
+		this.#searchRegistry?.invoke(commandId, args);
+	}
+	select(item) {
+		this.selection.replace(item);
+	}
+	selectMany(items) {
+		this.selection.selectMany(items);
+	}
+	deselect(item) {
+		this.selection.deselect(item);
+	}
+	clearSelection() {
+		this.selection.clear();
+	}
+	selectAll() {
+		if (this.selection.canSelectAll()) this.selection.selectAll();
+	}
+	/** The selection as stable `data-key` / `data-value` strings. */
+	get selectedKeys() {
+		return this.selection.selectedKeys;
+	}
+	/** The key of the item under the cursor, or `undefined`. */
+	get tickledKey() {
+		const id = this.tickled.tickledId;
+		return id ? keyForElement(id) : void 0;
+	}
+	/** Replace the selection with the items carrying these keys (unknown keys ignored). */
+	selectKeys(keys) {
+		this.selection.selectKeys(keys, (key) => this.#itemForKey(key));
+	}
+	/** Add items by key to the selection (multi-select modes only). */
+	addSelectedKeys(keys) {
+		this.selection.addKeys(keys, (key) => this.#itemForKey(key));
+	}
+	/** Remove items by key from the selection. */
+	removeSelectedKeys(keys) {
+		this.selection.removeKeys(keys, (key) => this.#itemForKey(key));
+	}
+	/**
+	* Move the cursor to the item with this key and scroll it into view.
+	* Under virtualization the key's index is scrolled into the rendered
+	* window first (a no-op for unknown keys).
+	*/
+	focusKey(key) {
+		if (this.#virtualActive()) {
+			const index = this.#allItems.findIndex((el) => keyForElement(el) === key);
+			if (index < 0) return;
+			const ul = this.renderRoot.querySelector(`ul`);
+			if (ul) {
+				const stride = this.itemHeight;
+				const viewportH = ul.clientHeight;
+				const top = index * stride;
+				const bottom = (index + 1) * stride;
+				const vt = ul.scrollTop;
+				const vh = viewportH;
+				let next = vt;
+				if (top < vt) next = top;
+				else if (bottom > vt + vh) next = bottom - vh;
+				if (next !== vt) ul.scrollTop = next;
+				this.#syncVirtualWindow(true);
+			}
+		}
+		const el = this.#itemForKey(key);
+		if (!el || el.parentNode !== this) return;
+		this.#pendingFocus = void 0;
+		this.tickled.focus(el);
+		el.scrollIntoView({
+			block: `nearest`,
+			inline: `nearest`
+		});
+	}
+	#revealCursor() {
+		const el = this.tickled.tickledId;
+		const key = el ? keyForElement(el) : void 0;
+		if (key !== void 0) this.focusKey(key);
+	}
+	#pageSize() {
+		const ul = this.#scrollList();
+		if (!ul) return 1;
+		const viewportH = ul.clientHeight;
+		if (this.#virtualActive()) return Math.max(1, Math.floor(viewportH / this.itemHeight));
+		const first = this.querySelector(`li[data-key]`);
+		if (!first) return 1;
+		const firstH = first.offsetHeight || this.itemHeight;
+		return Math.max(1, Math.floor(viewportH / firstH));
+	}
+	/** Move the cursor one page up (-1) or down (1) across the whole registry. */
+	#handlePage(direction) {
+		const page = this.#pageSize();
+		const items = this.#selectionOrder().filter((el) => !el.hasAttribute(`not-checked`));
+		if (items.length === 0) return;
+		const currentKey = this.tickled.tickledId ? keyForElement(this.tickled.tickledId) : void 0;
+		const currentIdx = currentKey !== void 0 ? items.findIndex((i) => keyForElement(i) === currentKey) : -1;
+		const fallback = direction === 1 ? page - 1 : 0;
+		const nextIdx = currentIdx < 0 ? fallback : currentIdx + direction * page;
+		this.tickled.handleKeyboardNavigation(items[Math.min(items.length - 1, Math.max(0, nextIdx))]);
+		this.#revealCursor();
+	}
+	#itemForKey(key) {
+		if (this.#virtualActive()) return this.#allItems.find((el) => keyForElement(el) === key);
+		for (const el of this.querySelectorAll(ITEM_SELECTOR)) {
+			if (this.#wrappedElements.has(el)) continue;
+			if (keyForElement(el) === key) return el;
+		}
+	}
+	/** The item carrying this `data-key`, or `undefined`. */
+	getItemByKey(key) {
+		return this.#itemForKey(key);
+	}
+	/**
+	* Snapshot selection (the checked set in `checked` mode), keyboard cursor
+	* and scroll as plain JSON keyed by `data-key` / `data-value`. Includes
+	* pending state for keys not currently in the list.
+	*/
+	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 : []),
+			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 list yet are applied as matching rows appear.
+	*/
+	setViewState(state) {
+		if (!this.#viewState.accepts(state)) return;
+		this.#viewState.restoring(() => {
+			if (state.selected) {
+				const index = this.#keyIndex();
+				this.selection.restoreKeys(state.selected, (key) => index.get(key));
+			}
+			if (state.focus !== void 0) this.#pendingFocus = state.focus;
+			if (state.scroll) this.#viewState.pendingScroll = state.scroll;
+			this.#viewState.notify();
+		});
+		this.#reconcileViewState();
+	}
+	clearPendingViewState() {
+		this.selection.clearPending();
+		this.#pendingFocus = void 0;
+		this.#viewState.pendingScroll = void 0;
+	}
+	/** Rows by key — the registry while virtualized, attached canonical rows otherwise. */
+	#keyIndex() {
+		if (this.#virtualActive()) return indexByKey(this.#allItems, keyForElement);
+		return indexByKey([...this.querySelectorAll(ITEM_SELECTOR)].filter((el) => !this.#wrappedElements.has(el)), keyForElement);
+	}
+	/** Whether a canonical row is still in the list (attached, or in the virtual registry). */
+	#isPresent(el) {
+		if (this.#virtualActive()) return this.#registryIndexOf(el) >= 0;
+		return el.parentNode === this || this.#wrappedElements.has(el);
+	}
+	/** Rows that left the data: deselected silently, keys kept pending. */
+	#demoteDeparted(items) {
+		if (items.length === 0 || !this.selection.demote(items)) return;
+		this._syncItemStates();
+		this.#viewState.notify(`data`);
+	}
+	/**
+	* After any item change: apply pending selection / cursor / scroll to rows
+	* that are now present, and send a departed keyboard cursor pending.
+	*/
+	#reconcileViewState() {
+		if (this.#reconcilingViewState) return;
+		this.#reconcilingViewState = true;
+		try {
+			this.#viewState.restoring(() => {
+				let index;
+				const lookup = (key) => (index ??= this.#keyIndex()).get(key);
+				this.selection.resolvePending(lookup);
+				const cursor = this.tickled.tickledId;
+				const gone = cursor !== void 0 && !this.#isPresent(cursor);
+				if (this.#pendingFocus === void 0 && !gone) return;
+				const departedKey = gone && this.tickled.inputMode === `keyboard` ? keyForElement(cursor) : void 0;
+				if (gone) this.tickled.clearTickled();
+				const focus = reconcileFocus(this.#pendingFocus, departedKey, (key) => lookup(key) !== void 0);
+				this.#pendingFocus = focus.pending;
+				if (focus.apply !== void 0) {
+					this.tickled.setInputMode(`keyboard`);
+					this.tickled.setTickled(lookup(focus.apply));
+					this.#viewState.notify();
+				}
+			});
+			this.#viewState.applyPendingScroll((scroll) => this.#applyScroll(scroll));
+		} finally {
+			this.#reconcilingViewState = false;
+		}
+	}
+	#captureScroll() {
+		const ul = this.#scrollList();
+		if (!ul) return void 0;
+		if (this.#virtualActive()) return captureVirtualScroll(ul.scrollTop, this.itemHeight, this.#allItems.length, (i) => keyForElement(this.#allItems[i]));
+		return captureElementScroll(ul, this._getVisibleItems(), keyForElement);
+	}
+	/** Returns `true` once the saved position is fully reached. */
+	#applyScroll(scroll) {
+		const ul = this.#scrollList();
+		if (!ul || ul.clientHeight === 0) return false;
+		if (this.#virtualActive()) {
+			const target = virtualScrollTarget(scroll, this.itemHeight, (key) => this.#allItems.findIndex((el) => keyForElement(el) === key));
+			if (target === void 0) return false;
+			const max = Math.max(0, this.#allItems.length * this.itemHeight - this.#measureViewport(ul));
+			ul.scrollTop = Math.max(0, Math.min(target, max));
+			this.#syncVirtualWindow();
+			return target <= max + 1;
+		}
+		if (!scroll.anchor) return scrollToOffset(ul, scroll.top);
+		const el = this.#keyIndex().get(scroll.anchor.key);
+		if (!el || el.hidden) return false;
+		return restoreElementScroll(ul, el, scroll.anchor.offset);
+	}
+	/**
+	* Keys of items currently intersecting the viewport — for prioritising
+	* viewport-first work (e.g. metadata/thumbnail fetches). A rect-intersection
+	* test against the scroll container over the already-created rows (the same
+	* cheap trick as `ixfx-detail-list.visibleKeys()`); hidden (filtered-out)
+	* and keyless items are omitted.
+	*/
+	visibleKeys() {
+		const container = this.renderRoot.querySelector(`ul`);
+		if (!container) return [];
+		const box = container.getBoundingClientRect();
+		const out = [];
+		for (const el of this._getVisibleItems()) {
+			const key = keyForElement(el);
+			if (key === void 0) continue;
+			const r = el.getBoundingClientRect();
+			if (r.bottom > box.top && r.top < box.bottom) out.push(key);
+		}
+		return out;
+	}
+	/**
+	* Keys of the currently rendered window (viewport + overscan) — the
+	* priority set for prefetching, mirroring `ixfx-grid-list.renderedKeys()`.
+	* Use {@link visibleKeys} for the strict viewport intersection. Keyless
+	* rows are omitted. Without virtualization, every visible row's key.
+	*/
+	renderedKeys() {
+		if (!this.#virtualActive()) {
+			const out = [];
+			for (const el of this._getVisibleItems()) {
+				const key = keyForElement(el);
+				if (key !== void 0) out.push(key);
+			}
+			return out;
+		}
+		const out = [];
+		for (let i = this.#windowStart; i < this.#windowEnd; i++) {
+			const el = this.#allItems[i];
+			if (!el) continue;
+			const key = keyForElement(el);
+			if (key !== void 0) out.push(key);
+		}
+		return out;
+	}
+	*selectedFilter(kind) {
+		const source = this.#virtualActive() ? this.#allItems : this.querySelectorAll(ITEM_SELECTOR);
+		const isChecked = (el) => {
+			if (this.interactionMode !== `checked`) return false;
+			return !(this.#customWrappers.get(el) ?? el).hasAttribute(`not-checked`) && this.selection.selected.has(el);
+		};
+		for (const el of source) {
+			if (!this.#virtualActive() && this.#wrappedElements.has(el)) continue;
+			if (el.hidden) continue;
+			switch (kind) {
+				case `selected`:
+					if (this.selection.selected.has(el)) yield el;
+					break;
+				case `checked`:
+					if (isChecked(el)) yield el;
+					break;
+				case `either`: if (this.selection.selected.has(el) || isChecked(el)) yield el;
+			}
+		}
+	}
+	/**
+	* Get the source object behind a row built from `items`. Returns
+	* `undefined` for declarative / programmatic elements.
+	*/
+	getItemData(item) {
+		return this.#itemData.get(item);
+	}
+	/**
+	* Adapter mode: re-render the row carrying `key` in place — scroll and
+	* selection are untouched. Unknown keys, and keys on rows not built from
+	* `items`, are ignored. A no-op unless `items` is set.
+	*
+	* Rows whose formatter returns a full row element are swapped for the fresh
+	* element; `<li>` rows are refilled. (A custom-element row with a
+	* non-element formatter result cannot be re-rendered in place and is left
+	* alone — have the formatter return a replacement element instead.)
+	*/
+	updateItem(key, data) {
+		if (this.items === void 0) return;
+		const el = this.getItemByKey(key);
+		if (!el || !this.#itemData.has(el)) return;
+		const index = this.#adapterIndexOf(el);
+		const fresh = this.formatter ? this.formatter(data, index) : data;
+		if (el instanceof HTMLLIElement) {
+			for (const child of [...el.childNodes]) child.remove();
+			this.#fillAdapterItem(el, fresh, data, index);
+			if (this.interactionMode === `checked`) this._syncCheckboxes();
+			this._syncItemStates();
+		} else if (fresh instanceof Element && this.#isRowElement(fresh)) {
+			if (fresh.tagName !== `LI` && !fresh.hasAttribute(`data-list-item`)) fresh.setAttribute(`data-list-item`, ``);
+			this.#stampAdapterKey(fresh, data);
+			this.#itemData.set(fresh, data);
+			this.#itemData.delete(el);
+			this.selection.remap((item) => item === el ? fresh : item);
+			if (this.#virtualActive()) this.#swapRegistry(el, fresh);
+			el.replaceWith(fresh);
+			if (this.interactionMode === `checked`) this._syncCheckboxes();
+			this._syncItemStates();
+		}
+		if (this.keyProperty) {
+			const sourceIndex = this.items.findIndex((entry) => this.#adapterProperty(entry, this.keyProperty) !== void 0 && String(this.#adapterProperty(entry, this.keyProperty)) === key);
+			if (sourceIndex >= 0) {
+				const next = [...this.items];
+				next[sourceIndex] = data;
+				this.#suspendAdapterRebuild = true;
+				this.items = next;
+			}
+		}
+	}
+	#rebuildFromAdapter() {
+		const source = this.items ?? [];
+		const previous = [...this.selection.selected];
+		const anchorKey = this.selection.anchor ? keyForElement(this.selection.anchor) : void 0;
+		this.#customWrappers.clear();
+		this.replaceChildren(...source.map((item, index) => this.#createAdapterItem(item, index)));
+		this.#rekeySelection(previous, anchorKey, this.querySelectorAll(ITEM_SELECTOR));
+		if (this.interactionMode === `checked`) this._syncCheckboxes();
+		this._syncItemStates();
+		this._syncNativeDraggable();
+		this.#nativeDrag.refreshDraggable();
+		this.#reconcileViewState();
+	}
+	/** Swap a rebuilt-away selection onto same-key rows; unmatched keys go pending. */
+	#rekeySelection(previous, anchorKey, rows) {
+		if (previous.length === 0 && anchorKey === void 0) return;
+		const { live, gone, anchor } = rekeySelection(previous, anchorKey, rows, keyForElement);
+		this.selection.demote(gone);
+		this.selection.seed(live, anchor);
+	}
+	#createAdapterItem(item, index) {
+		const content = this.formatter ? this.formatter(item, index) : item;
+		if (content instanceof Element && this.#isRowElement(content)) {
+			if (content.tagName !== `LI` && !content.hasAttribute(`data-list-item`)) content.setAttribute(`data-list-item`, ``);
+			this.#stampAdapterKey(content, item);
+			this.#itemData.set(content, item);
+			return content;
+		}
+		const li = document.createElement(`li`);
+		this.#fillAdapterItem(li, content, item, index);
+		return li;
+	}
+	#fillAdapterItem(li, content, item, index) {
+		if (typeof content === `string`) li.textContent = content;
+		else if (content instanceof Node) li.appendChild(content);
+		else if (this.formatter && content !== void 0 && content !== null) render(content, li);
+		this.#decorateAdapterItem(li, item, index);
+		this.#stampAdapterKey(li, item);
+		this.#itemData.set(li, item);
+	}
+	/**
+	* Apply the per-item icon / text colour / badge to a built row. Split out
+	* from {@link #fillAdapterItem} so the parts stay readable.
+	*/
+	#decorateAdapterItem(li, item, index) {
+		const textColor = appearanceColor(this.textColor?.(item, index));
+		if (textColor !== void 0) li.style.color = textColor;
+		else li.style.removeProperty(`color`);
+		const icon = this.icon?.(item, index);
+		if (!appearanceAbsent(icon)) {
+			const holder = document.createElement(`span`);
+			holder.className = `item-icon`;
+			holder.style.cssText = ITEM_ICON_EL_CSS;
+			const iconColor = appearanceColor(this.iconColor?.(item, index));
+			if (iconColor !== void 0) holder.style.color = iconColor;
+			if (icon instanceof Node) holder.appendChild(icon);
+			else render(icon, holder);
+			li.prepend(holder);
+		}
+		const badge = this.badge?.(item, index);
+		if (!appearanceAbsent(badge)) {
+			const holder = document.createElement(`span`);
+			holder.className = `item-badge`;
+			holder.style.cssText = ITEM_BADGE_EL_CSS;
+			if (badge instanceof Node) holder.appendChild(badge);
+			else render(badge, holder);
+			li.appendChild(holder);
+		}
+	}
+	/**
+	* Whether a formatter-produced element is a whole row (used directly)
+	* rather than row content (rendered into a `<li>`): an `<li>`, already
+	* marked `[data-list-item]`, or a custom element.
+	*/
+	#isRowElement(content) {
+		return content.tagName === `LI` || content.hasAttribute(`data-list-item`) || content.tagName.includes(`-`);
+	}
+	#stampAdapterKey(el, item) {
+		if (!this.keyProperty) return;
+		const key = this.#adapterProperty(item, this.keyProperty);
+		if (key !== void 0 && key !== null) el.setAttribute(`data-key`, String(key));
+	}
+	#adapterProperty(item, prop) {
+		if (typeof item !== `object` || item === null || !(prop in item)) return void 0;
+		return item[prop];
+	}
+	/** Ordinal of an adapter-built row among adapter-built rows in DOM order. */
+	#adapterIndexOf(el) {
+		if (this.#virtualActive()) return this.#registryIndexOf(el);
+		let index = 0;
+		for (const item of this.querySelectorAll(ITEM_SELECTOR)) {
+			if (item === el) return index;
+			if (this.#itemData.has(item)) index++;
+		}
+		return index;
+	}
+	/**
+	* Adapter rebuild for the virtualized window: same content as
+	* {@link #rebuildFromAdapter} but rows become the recycle registry and
+	* only the window attaches.
+	*/
+	#rebuildAdapterVirtual() {
+		const source = this.items ?? [];
+		const previous = [...this.selection.selected];
+		const anchorKey = this.selection.anchor ? keyForElement(this.selection.anchor) : void 0;
+		this.#customWrappers.clear();
+		this.#pool = document.createDocumentFragment();
+		this.#pendingAnimate = [];
+		this.#allItems = source.map((item, index) => this.#createAdapterItem(item, index));
+		for (const el of this.#allItems) this.#animatedItems.add(el);
+		this.#rekeySelection(previous, anchorKey, this.#allItems);
+		this.#syncVirtualWindow(true);
+	}
+	#virtualActive() {
+		return this.virtualize && this.itemHeight > 0;
+	}
+	/**
+	* Selection order: the full registry while virtualized (so `selectAll` and
+	* range operations span pooled rows too — they hold live element refs), the
+	* attached rows otherwise.
+	*/
+	#selectionOrder() {
+		if (!this.#virtualActive()) return this._getVisibleItems();
+		return this.#allItems.filter((el) => {
+			if (el.hidden) return false;
+			if (this.filterPredicate && !this.filterPredicate(el)) return false;
+			return true;
+		});
+	}
+	/** Registry index of a row, resolving wrapped inners to their wrapper. */
+	#registryIndexOf(el) {
+		const direct = this.#allItems.indexOf(el);
+		if (direct >= 0) return direct;
+		if (this.#wrappedElements.has(el)) {
+			for (const [wrapper, inner] of this.#customWrappers) if (inner === el) return this.#allItems.indexOf(wrapper);
+		}
+		return -1;
+	}
+	#swapRegistry(oldEl, newEl) {
+		const i = this.#allItems.indexOf(oldEl);
+		if (i >= 0) this.#allItems[i] = newEl;
+	}
+	#cleanupWrapperRefs(el) {
+		if (this.#customWrappers.has(el)) {
+			const inner = this.#customWrappers.get(el);
+			this.#customWrappers.delete(el);
+			if (inner) this.#wrappedElements.delete(inner);
+		}
+		if (this.#wrappedElements.has(el)) {
+			for (const [wrapper, inner] of this.#customWrappers) if (inner === el) {
+				this.#customWrappers.delete(wrapper);
+				break;
+			}
+			this.#wrappedElements.delete(el);
+		}
+	}
+	/**
+	* Global registry index for an attached row, derived from its DOM position:
+	* nodes after the bottom spacer are end-of-list appends, nodes before the
+	* top spacer are prepends, otherwise window-start plus preceding rows.
+	*/
+	#globalIndexForAttached(el) {
+		let count = 0;
+		let sib = el.previousElementSibling;
+		while (sib) {
+			if (sib === this.#topSpacer) return this.#windowStart + count;
+			if (sib === this.#bottomSpacer) return this.#allItems.length;
+			if (sib.matches(ITEM_SELECTOR)) count++;
+			sib = sib.previousElementSibling;
+		}
+		return count;
+	}
+	/**
+	* Fold consumer-side DOM edits into the registry. Our own window moves
+	* reconcile to no-ops (known nodes already pooled or correctly placed);
+	* genuinely new nodes are spliced by DOM position; removed-then-gone nodes
+	* are dropped. Returns whether the registry changed.
+	*/
+	#reconcileRecords(records) {
+		let changed = false;
+		const fresh = [];
+		const removed = [];
+		for (const record of records) {
+			for (const node of record.addedNodes) {
+				if (!(node instanceof Element) || node.parentNode !== this) continue;
+				if (node.hasAttribute(`data-virtual-spacer`) || !node.matches(ITEM_SELECTOR)) continue;
+				const known = this.#registryIndexOf(node);
+				if (known < 0) {
+					const at = Math.min(this.#globalIndexForAttached(node), this.#allItems.length);
+					this.#allItems.splice(at, 0, node);
+					fresh.push(node);
+					changed = true;
+				} else if (this.#globalIndexForAttached(node) !== known) {
+					const at = Math.min(this.#globalIndexForAttached(node), this.#allItems.length - 1);
+					this.#allItems.splice(known, 1);
+					this.#allItems.splice(at, 0, node);
+					changed = true;
+				}
+			}
+			for (const node of record.removedNodes) {
+				if (!(node instanceof Element) || node.hasAttribute(`data-virtual-spacer`)) continue;
+				const known = this.#registryIndexOf(node);
+				if (known < 0) continue;
+				if (node.parentNode === this.#pool || node.parentNode === this) continue;
+				this.#allItems.splice(known, 1);
+				removed.push(node);
+				changed = true;
+			}
+		}
+		this.#demoteDeparted(removed);
+		if (fresh.length > 0) {
+			if (this.#isBulkPopulate(fresh.length)) for (const el of fresh) this.#animatedItems.add(el);
+			else this.#pendingAnimate.push(...fresh);
+		}
+		if (changed && this.interactionMode === `checked`) this._syncCheckboxes();
+		if (changed) this.search.refresh();
+		return changed;
+	}
+	/** Consume queued observer records first so a sync never drops a row. */
+	#drainMutations() {
+		const pending = this.#itemObserver?.takeRecords() ?? [];
+		return pending.length > 0 ? this.#reconcileRecords(pending) : false;
+	}
+	#scrollList() {
+		return this.renderRoot.querySelector(`ul`);
+	}
+	#measureViewport(ul) {
+		if (!ul) return this.#lastViewportH;
+		const h = ul.clientHeight || ul.getBoundingClientRect().height || 0;
+		if (h > 0) this.#lastViewportH = h;
+		return this.#lastViewportH;
+	}
+	#ensureSpacers() {
+		if (this.#topSpacer && this.#bottomSpacer) return;
+		const make = () => {
+			const li = document.createElement(`li`);
+			li.setAttribute(`data-virtual-spacer`, ``);
+			li.setAttribute(`aria-hidden`, `true`);
+			return li;
+		};
+		this.#topSpacer = make();
+		this.#bottomSpacer = make();
+	}
+	#ensureResizeObserved() {
+		const ul = this.#scrollList();
+		if (!ul) return;
+		this.#resizeObserver ??= new ResizeObserver(() => {
+			this.#syncVirtualWindow();
+			this.#scheduleViewportChangeEmit();
+			this.#reconcileViewState();
+		});
+		this.#resizeObserver.observe(ul);
+	}
+	#onScroll;
+	/**
+	* Reconcile the attached light DOM with the overscanned window. Rows are
+	* moved by identity (never recreated); selection, cursor and component
+	* state travel with them.
+	*/
+	#syncVirtualWindow(force = false) {
+		if (!this.#virtualActive() || !this.isConnected) return;
+		const changed = this.#drainMutations() || force;
+		this.#ensureResizeObserved();
+		const count = this.#allItems.length;
+		const ul = this.#scrollList();
+		const stride = this.itemHeight;
+		const viewportH = this.#measureViewport(ul);
+		const maxScroll = Math.max(0, count * stride - viewportH);
+		const offset = Math.min(Math.max(0, ul ? ul.scrollTop : 0), maxScroll);
+		if (ul && Math.abs(ul.scrollTop - offset) > .5) ul.scrollTop = offset;
+		const firstVisible = Math.floor(offset / stride);
+		const lastVisible = Math.ceil((offset + viewportH) / stride);
+		const start = count === 0 ? 0 : Math.max(0, firstVisible - VIRTUAL_OVERSCAN);
+		const end = Math.min(count, lastVisible + VIRTUAL_OVERSCAN);
+		if (!changed && start === this.#windowStart && end === this.#windowEnd) return;
+		if (count === 0) {
+			if (this.#allItems.length > 0) this.#pool.append(...this.#allItems);
+			this.replaceChildren();
+		} else {
+			this.#ensureSpacers();
+			const top = this.#topSpacer;
+			const bottom = this.#bottomSpacer;
+			if (!top || !bottom) return;
+			top.style.height = `${start * stride}px`;
+			bottom.style.height = `${Math.max(0, (count - end) * stride)}px`;
+			const rows = this.#allItems.slice(start, end);
+			const parked = [...this.#allItems.slice(0, start), ...this.#allItems.slice(end)];
+			if (parked.length > 0) this.#pool.append(...parked);
+			this.replaceChildren(top, ...rows, bottom);
+		}
+		this.#windowStart = start;
+		this.#windowEnd = end;
+		if (this.interactionMode === `checked`) this._syncCheckboxes();
+		this._syncItemStates();
+		const totalCount = this.#selectionOrder().length;
+		for (let i = start; i < end; i++) {
+			const el = this.#allItems[i];
+			if (el) this.#applyRowState(el, i + 1, totalCount);
+		}
+		const pending = this.#pendingAnimate;
+		this.#pendingAnimate = [];
+		for (const el of pending) {
+			this.#animatedItems.add(el);
+			if (el.parentNode === this) animateListItemIn(el);
+		}
+		this.search.repaintHighlights();
+		if (changed) this.#reconcileViewState();
+	}
+	/** Per-attach state the attached sweep can't cover (it only sees the window). */
+	#applyRowState(el, posInSet, setSize) {
+		if (el instanceof HTMLElement) {
+			el.draggable = this.itemsDraggable && this._isCheckable(el) && !el.hasAttribute(`data-editing`);
+			if (posInSet !== void 0 && setSize !== void 0) {
+				el.setAttribute(`aria-setsize`, String(setSize));
+				el.setAttribute(`aria-posinset`, String(posInSet));
+				if (!el.hasAttribute(`role`) || el.hasAttribute(`data-aria-role`)) {
+					el.setAttribute(`role`, `option`);
+					el.setAttribute(`data-aria-role`, ``);
+					el.setAttribute(`aria-selected`, String(this.selection.selected.has(el)));
+				}
+			}
+		}
+		el.removeAttribute(`data-marquee`);
+		el.removeAttribute(`data-drag-origin`);
+		el.removeAttribute(`data-drop-target`);
+	}
+	/**
+	* Leave virtualization: reattach every registry row in order and drop the
+	* spacers and pool. Selection (live refs) and cursor survive untouched.
+	*/
+	#teardownVirtualWindow() {
+		for (const el of this.#allItems) this.#animatedItems.add(el);
+		if (this.#allItems.length > 0) this.replaceChildren(...this.#allItems);
+		else this.replaceChildren();
+		this.#pool = document.createDocumentFragment();
+		this.#topSpacer = void 0;
+		this.#bottomSpacer = void 0;
+		this.#windowStart = 0;
+		this.#windowEnd = 0;
+		this.#pendingAnimate = [];
+		this._syncCheckboxes();
+		this._syncItemStates();
+		this._syncNativeDraggable();
+		this.#nativeDrag.refreshDraggable();
+		this.#scheduleViewportChangeEmit();
+	}
+	/** Coalesce content/layout viewport checks to at most one animation frame. */
+	#scheduleViewportChangeEmit() {
+		if (this.#scrollRaf !== 0) return;
+		this.#scrollRaf = requestAnimationFrame(() => {
+			this.#scrollRaf = 0;
+			this.#syncVirtualWindow();
+			this.#emitViewportChangeIfChanged();
+		});
+	}
+	/**
+	* Dispatch `vertical-list-viewport-change` with the current key sets — unless
+	* neither set changed since the last dispatch, so coalesced frames and
+	* no-op scrolls stay silent.
+	*/
+	#emitViewportChangeIfChanged() {
+		const renderedKeys = this.renderedKeys();
+		const visibleKeys = this.visibleKeys();
+		if (sameKeys(this.#lastViewportRenderedKeys, renderedKeys) && sameKeys(this.#lastViewportVisibleKeys, visibleKeys)) return;
+		this.#lastViewportRenderedKeys = renderedKeys;
+		this.#lastViewportVisibleKeys = visibleKeys;
+		this._dispatch(`vertical-list-viewport-change`, {
+			renderedKeys,
+			visibleKeys
+		});
+	}
+	_getVisibleItems() {
+		return Array.from(this.querySelectorAll(ITEM_SELECTOR)).filter((el) => {
+			if (this.#wrappedElements.has(el)) return false;
+			if (el.hidden) return false;
+			if (this.filterPredicate && !this.filterPredicate(el)) return false;
+			return true;
+		});
+	}
+	_isCheckable(item) {
+		if (this.interactionMode !== `checked`) return true;
+		return !(this.#customWrappers.get(item) ?? item).hasAttribute(`not-checked`);
+	}
+	_syncItemStates() {
+		for (const el of this.querySelectorAll(ITEM_SELECTOR)) {
+			if (this.#wrappedElements.has(el)) continue;
+			const item = this.#customWrappers.get(el) ?? el;
+			el.toggleAttribute(`data-tickled`, this.tickled.isTickled(el));
+			el.toggleAttribute(`data-selected`, this.selection.selected.has(el));
+			if (el.hasAttribute(`data-aria-role`)) el.setAttribute(`aria-selected`, String(this.selection.selected.has(el)));
+			if (this.interactionMode === `checked`) el.toggleAttribute(`data-checked`, !item.hasAttribute(`not-checked`) && this.selection.selected.has(el));
+			else el.removeAttribute(`data-checked`);
+		}
+		this.dataset.inputMode = this.tickled.inputMode;
+		this._syncCheckboxes();
+	}
+	_syncCheckboxes() {
+		const inCheckedMode = this.interactionMode === `checked`;
+		const wantsCustom = typeof this.checkboxRenderer === `function`;
+		const roots = this.#virtualActive() ? [this, this.#pool] : [this];
+		if (inCheckedMode) for (const root of roots) for (const inner of Array.from(root.children)) {
+			if (!inner.hasAttribute(`data-list-item`)) continue;
+			if (inner.parentNode !== root) continue;
+			const wrapper = document.createElement(`li`);
+			wrapper.className = `ixfx-custom-row`;
+			const key = inner.getAttribute(`data-key`);
+			const label = inner.getAttribute(`data-search-label`);
+			if (key !== null) wrapper.setAttribute(`data-key`, key);
+			if (label !== null) wrapper.setAttribute(`data-search-label`, label);
+			inner.removeAttribute(`data-list-item`);
+			root.insertBefore(wrapper, inner);
+			wrapper.appendChild(inner);
+			this.#customWrappers.set(wrapper, inner);
+			this.#wrappedElements.add(inner);
+			if (this.#itemData.has(inner)) this.#itemData.set(wrapper, this.#itemData.get(inner));
+			if (this.#virtualActive()) this.#swapRegistry(inner, wrapper);
+		}
+		else {
+			for (const [wrapper, inner] of this.#customWrappers) {
+				if (wrapper.parentNode !== this && wrapper.parentNode !== this.#pool) continue;
+				inner.setAttribute(`data-list-item`, ``);
+				const parent = wrapper.parentNode;
+				if (parent) parent.insertBefore(inner, wrapper);
+				wrapper.remove();
+				this.#itemData.delete(wrapper);
+				if (this.#virtualActive()) this.#swapRegistry(wrapper, inner);
+			}
+			this.#customWrappers.clear();
+			this.#wrappedElements.clear();
+		}
+		for (const el of this.querySelectorAll(`li`)) {
+			const existing = el.querySelector(`.ixfx-list-checkbox`);
+			if (!inCheckedMode) {
+				if (existing) existing.remove();
+				continue;
+			}
+			if ((this.#customWrappers.get(el) ?? el).hasAttribute(`not-checked`)) {
+				if (existing) existing.remove();
+				continue;
+			}
+			const existingIsCustom = existing?.classList.contains(`ixfx-list-checkbox-custom`) ?? false;
+			if (existing && existingIsCustom !== wantsCustom) existing.remove();
+			let cb = el.querySelector(`.ixfx-list-checkbox`);
+			if (!cb) {
+				if (wantsCustom) {
+					const opts = this.checkboxRenderer;
+					const margin = opts.margin ?? `0`;
+					const width = opts.width ?? `24px`;
+					cb = this._createCustomCheckbox(el, margin, width);
+				} else cb = this._createNativeCheckboxCell(el);
+				el.prepend(cb);
+			}
+			const checked = this.selection.selected.has(el);
+			if (wantsCustom) {
+				cb.setAttribute(`aria-checked`, String(checked));
+				cb.toggleAttribute(`data-checked`, checked);
+				if (this.checkboxRenderer) {
+					const renderer = typeof this.checkboxRenderer === `function` ? this.checkboxRenderer : this.checkboxRenderer.renderer;
+					render(renderer(checked), cb);
+				}
+			} else {
+				const input = cb.querySelector(`input.ixfx-list-checkbox`);
+				if (input) input.checked = checked;
+			}
+		}
+	}
+	/**
+	* Native checkbox cell: a span that stretches to the row's full cross-axis
+	* (so the entire column height is a click target) with a real `<input>`
+	* centred inside. The span owns the click; the input is purely visual and
+	* has `pointer-events:none` so a single click produces one toggle.
+	*/
+	_createNativeCheckboxCell(el) {
+		const cell = document.createElement(`span`);
+		cell.className = `ixfx-list-checkbox ixfx-list-checkbox-native`;
+		cell.style.cssText = `display:inline-flex;align-items:center;justify-content:center;flex-shrink:0;align-self:stretch;width:18px;margin:0 6px 0 0;cursor:pointer;pointer-events:auto`;
+		cell.tabIndex = -1;
+		cell.setAttribute(`role`, `checkbox`);
+		cell.setAttribute(`part`, `checkbox`);
+		cell.addEventListener(`click`, (e) => {
+			e.stopPropagation();
+			this.selection.toggle(el);
+		});
+		const input = document.createElement(`input`);
+		input.type = `checkbox`;
+		input.className = `ixfx-list-checkbox`;
+		input.style.cssText = `pointer-events:none;cursor:pointer;margin:0`;
+		cell.appendChild(input);
+		return cell;
+	}
+	/**
+	* Custom checkbox cell: same shape as the native cell (a stretching span)
+	* so behaviour is identical. The renderer's content goes inside.
+	*/
+	_createCustomCheckbox(el, margin, width) {
+		const span = document.createElement(`span`);
+		span.className = `ixfx-list-checkbox ixfx-list-checkbox-custom`;
+		span.style.cssText = `display:inline-flex;align-items:center;justify-content:center;flex-shrink:0;align-self:stretch;width:${width};margin:${margin};cursor:pointer;pointer-events:auto`;
+		span.tabIndex = -1;
+		span.setAttribute(`role`, `checkbox`);
+		span.setAttribute(`part`, `checkbox`);
+		span.addEventListener(`click`, (e) => {
+			e.stopPropagation();
+			this.selection.toggle(el);
+		});
+		return span;
+	}
+	_findListItem(path) {
+		for (const target of path) {
+			if (!(target instanceof Element)) continue;
+			if (target === this) break;
+			if (target.parentElement === this && target.matches(ITEM_SELECTOR)) return target;
+		}
+	}
+	_dispatch(name, detail) {
+		this.dispatchEvent(new CustomEvent(name, {
+			detail,
+			bubbles: true,
+			composed: true
+		}));
+	}
+	_dispatchCancelable(name, detail) {
+		return this.dispatchEvent(new CustomEvent(name, {
+			detail,
+			bubbles: true,
+			composed: true,
+			cancelable: true
+		}));
+	}
+	_activateItem(item) {
+		if (this.interactionMode !== `manual`) this.selection.replace(item);
+		this._dispatch(`list-activate`, { item });
+	}
+	activateKey(key) {
+		const item = this.#itemForKey(key);
+		if (item) this._activateItem(item);
+	}
+	/** The row (or `undefined` for empty space) the last `list-drag-over` was fired for. */
+	#dragOver;
+	/** Tell the consumer the drag left its last target and drop the highlight. */
+	#clearDropTarget() {
+		const last = this.#dragOver;
+		this.#dragOver = void 0;
+		this.#highlightDropTarget(void 0, false);
+		if (last) this._dispatch(`list-drag-leave`, { key: last.item ? keyForElement(last.item) : void 0 });
+	}
+	#dropTargetEl;
+	/** Mark one row (or, for empty space, the host) as the drop target. */
+	#highlightDropTarget(item, active) {
+		this.#dropTargetEl?.removeAttribute(`data-drop-target`);
+		this.#dropTargetEl = active ? item : void 0;
+		this.toggleAttribute(`data-drop-target`, active && item === void 0);
+		if (active && item) item.setAttribute(`data-drop-target`, ``);
+	}
+	/**
+	* Select the row if it is not already, then fire `list-context-menu`.
+	* Returns false when a listener cancelled it (the native menu is then suppressed).
+	*/
+	#requestContextMenu(item, x, y) {
+		if (!this.selection.selected.has(item) && this.interactionMode !== `manual` && this._isCheckable(item)) this.selection.replace(item);
+		return this._dispatchCancelable(`list-context-menu`, {
+			key: keyForElement(item),
+			item,
+			x,
+			y,
+			selectedKeys: this.selection.selectedKeys
+		});
+	}
+	#edit;
+	/** The key of the row being edited, if any. */
+	get editingKey() {
+		return this.#edit?.key;
+	}
+	#isEditEvent(e) {
+		return this.#edit !== void 0 && e.composedPath().includes(this.#edit.label);
+	}
+	/**
+	* Edit a row's label in place with an `ixfx-editable-label`. The editor
+	* replaces the row's `[data-edit-label]` element (else the whole row) and
+	* the original content returns when editing ends. Fires `list-edit-commit`
+	* `{ key, value }` when the text changed, otherwise `list-edit-cancel`
+	* `{ key }` (Escape, an unchanged value, or one the label rejects). The list
+	* never rewrites the label itself — update your data in response.
+	*
+	* Returns false when `editValidator` is not set, or the row is unknown or
+	* not currently rendered.
+	*/
+	beginEdit(key) {
+		this.#finishEdit();
+		const validate = this.editValidator;
+		if (!validate) return false;
+		const row = this.#itemForKey(key);
+		if (!(row instanceof HTMLElement) || row.parentNode !== this) return false;
+		const container = row.querySelector(`[data-edit-label]`) ?? row;
+		const value = container.getAttribute(`data-edit-value`) ?? container.textContent?.trim() ?? ``;
+		const label = document.createElement(`ixfx-editable-label`);
+		label.mode = `label`;
+		label.value = value;
+		label.validator = (text) => validate(text, key);
+		label.style.cssText = `flex:1;min-width:0;--label-align:left;--label-padding:0 var(--space-xs,3px)`;
+		const edit = {
+			key,
+			row,
+			container,
+			saved: [...container.childNodes],
+			label,
+			committed: void 0,
+			refocus: false
+		};
+		this.#edit = edit;
+		label.addEventListener(`change`, (e) => {
+			e.stopPropagation();
+			edit.committed = e.detail.value;
+		});
+		label.addEventListener(`input`, (e) => e.stopPropagation());
+		label.addEventListener(`keydown`, (e) => {
+			edit.refocus = e.key === `Enter` || e.key === `Escape`;
+		});
+		for (const type of [`pointerdown`, `dragstart`]) label.addEventListener(type, (e) => e.stopPropagation());
+		label.addEventListener(`focusout`, () => this.#finishEdit());
+		container.replaceChildren(label);
+		row.setAttribute(`data-editing`, ``);
+		row.draggable = false;
+		row.scrollIntoView({
+			block: `nearest`,
+			inline: `nearest`
+		});
+		label.updateComplete.then(() => {
+			if (this.#edit === edit) label.shadowRoot?.querySelector(`.content`)?.click();
+		});
+		return true;
+	}
+	/** Restore the row's content and report how the edit ended. */
+	#finishEdit() {
+		const edit = this.#edit;
+		if (!edit) return;
+		this.#edit = void 0;
+		if (edit.container.isConnected) edit.container.replaceChildren(...edit.saved);
+		edit.row.removeAttribute(`data-editing`);
+		this.#applyRowState(edit.row);
+		if (edit.refocus) this.focus();
+		if (edit.committed === void 0) this._dispatch(`list-edit-cancel`, { key: edit.key });
+		else this._dispatch(`list-edit-commit`, {
+			key: edit.key,
+			value: edit.committed
+		});
+	}
+	static {
+		this.styles = [
+			themeFallbacks,
+			scrollFadeStyles(`y`),
+			listSearchStyles,
+			css`
+    :host {
+      display: block;
+      position: relative;
+      background: var(--list-bg, var(--surface-3));
+      color: var(--list-text, var(--surface-3-text));
+      border-radius: var(--list-radius, var(--radius-s));
+      border: 1px solid var(--list-border, var(--border));
+      width: 100%;
+      height: 100%;
+      overflow: hidden;
+      box-sizing: border-box;
+      outline: none;
+      --ixfx-list-item-padding: var(--ixfx-list-item-padding, var(--list-item-padding, 4px var(--space-m, 8px)));
+      --_item-padding:
+        var(--ixfx-list-item-padding, var(--list-item-padding, 0 var(--space-xs, 3px)));
+    }
+
+    :host(:focus-visible) {
+      outline: 2px solid var(--accent);
+      outline-offset: 2px;
+    }
+
+    .container {
+      position: relative;
+      width: 100%;
+      height: 100%;
+    }
+
+    ul {
+      list-style: none;
+      margin: 0;
+      padding: 0;
+      width: 100%;
+      height: 100%;
+      overflow-x: hidden;
+      overflow-y: auto;
+      box-sizing: border-box;
+      /* Scrollbar theming: end users override these CSS variables to control
+         the native scrollbar (scrollbar-width, scrollbar-gutter, scrollbar-color). */
+      scrollbar-width: var(--list-scrollbar-width, auto);
+      scrollbar-gutter: var(--list-scrollbar-gutter, auto);
+      scrollbar-color: var(--list-scrollbar-color, auto);
+    }
+
+    ::slotted([hidden]) {
+      display: none !important;
+    }
+
+    ::slotted(li) {
+      display: flex;
+      align-items: center;
+      padding: var(--_item-padding);
+      /* Inset each row from the scroll container's edges (margin, not padding:
+         padding is inside the border box, so the tickle/selection outlines
+         would still sit flush against the edge and be clipped). */
+      margin: 0 var(--list-gutter, 4px);
+      min-height: var(--list-item-height, 28px);
+      cursor: pointer;
+      user-select: none;
+      transition: background var(--transition, 0.1s ease-out),
+                  outline-color var(--transition, 0.1s ease-out);
+      box-sizing: border-box;
+      outline: 1px solid transparent;
+    }
+
+    /* Per-item icon / badge (adapter mode) are styled inline by
+       #decorateAdapterItem — ::slotted() only reaches the host's direct
+       children, and these spans live inside a slotted <li>. */
+
+    /* Custom shadow-DOM components handle their own internal layout/padding.
+       Wrapped in :where() so the selector stays at zero specificity and a
+       consumer's own :host rule (e.g. display: flex) wins without
+       needing !important. */
+    :where(::slotted([data-list-item])) {
+      display: block;
+      margin: 0 var(--list-gutter, 4px);
+      cursor: pointer;
+      user-select: none;
+      transition: background var(--transition, 0.1s ease-out),
+                  outline-color var(--transition, 0.1s ease-out);
+      outline: 1px solid transparent;
+    }
+
+    /* Virtualization spacers: plain height holders bracketing the rendered
+       window. Attribute specificity beats ::slotted(li) so none of the row
+       layout (flex, padding, min-height, gutters) applies; pointer events are
+       off so clicks land on the scroll container, not a phantom row. */
+    ::slotted([data-virtual-spacer]) {
+      display: block;
+      padding: 0;
+      margin: 0;
+      border: none;
+      min-height: 0;
+      overflow: hidden;
+      cursor: default;
+      pointer-events: none;
+      outline: none;
+      user-select: none;
+    }
+
+    /* In checked mode, only the checkbox column is clickable; the row body
+       gets a default cursor so it doesn't suggest otherwise. */
+    :host([interaction-mode="checked"]) ::slotted(li),
+    :host([interaction-mode="checked"]) ::slotted([data-list-item]) {
+      cursor: default;
+    }
+
+    /* Wrapper inserted around custom [data-list-item] elements in checked mode.
+       Provides the flex layout so the injected checkbox can stretch to the
+       row's full height via align-self:stretch. */
+    .ixfx-custom-row {
+      display: flex;
+      align-items: center;
+      min-height: var(--list-item-height, 28px);
+      box-sizing: border-box;
+      cursor: default;
+      user-select: none;
+    }
+
+    ::slotted([data-tickled]) {
+      background: var(--item-bg-tickled);
+      outline: var(--item-border-tickled);
+    }
+
+    ::slotted([data-selected]) {
+      background: var(--item-bg-selected);
+      color: var(--item-text-selected);
+      outline: 1px solid transparent;
+    }
+
+    ::slotted([data-selected][data-tickled]) {
+      background: var(--item-bg-selected-tickled);
+      outline: 2px dashed var(--surface-3);
+      outline-offset: -2px;
+    }
+
+    /* Drag-select (marquee) rectangle + covered-row preview.
+       Style hooks: part="marquee", --vertical-list-marquee-border,
+       --vertical-list-marquee-fill. */
+    .marquee {
+      position: absolute;
+      pointer-events: none;
+      z-index: 5;
+      border: 1px solid var(--vertical-list-marquee-border, var(--accent));
+      background: var(--vertical-list-marquee-fill, color-mix(in srgb, var(--accent) 15%, transparent));
+    }
+
+    ::slotted([data-marquee]) {
+      background: var(--item-bg-selected);
+      color: var(--item-text-selected);
+    }
+
+    ::slotted([data-drag-origin]) {
+      opacity: 0.6;
+    }
+
+    /* Native drop target: the row under a drag, or the whole list over empty space. */
+    ::slotted([data-drop-target]) {
+      background: var(--list-drop-target-bg, color-mix(in srgb, var(--accent) 25%, transparent));
+      outline: 2px solid var(--list-drop-target-outline, var(--accent));
+      outline-offset: -2px;
+    }
+
+    :host([data-drop-target]) {
+      outline: 2px solid var(--list-drop-target-outline, var(--accent));
+      outline-offset: -2px;
+    }
+
+    /* checked mode: checkbox (injected into li) communicates selection — suppress bg highlight */
+    :host([interaction-mode="checked"]) ::slotted([data-selected]) {
+      background: transparent;
+      color: inherit;
+      outline: 1px solid transparent;
+      padding: var(--space-s);
+    }
+
+    :host([interaction-mode="checked"]) ::slotted([data-selected][data-tickled]) {
+      background: var(--item-bg-tickled);
+      color: inherit;
+      outline: var(--item-border-tickled);
+    }
+  `
+		];
+	}
+	render() {
+		const role = this.getAttribute(`role`) ? void 0 : `listbox`;
+		const ariaMulti = this.selectionMode === `multiple`;
+		return html`
+      <div class="container">
+        <ul
+          part="list"
+          class="scroll-fade-y"
+          role=${ifDefined(role)}
+          aria-multiselectable=${ariaMulti ? `true` : `false`}
+          @scroll=${this.#onScroll}
+        >
+          <slot></slot>
+        </ul>
+        ${this.#marqueeRect ? html`<div class="marquee" part="marquee" style=${this.#marqueeStyle(this.#marqueeRect)}></div>` : ``}
+        ${this.search.renderField()}
+      </div>
+    `;
+	}
+};
+__decorate([property({
+	type: String,
+	attribute: `selection-mode`
+})], VerticalListElement.prototype, "selectionMode", void 0);
+__decorate([property({
+	type: String,
+	attribute: `interaction-mode`
+})], VerticalListElement.prototype, "interactionMode", void 0);
+__decorate([property({ attribute: false })], VerticalListElement.prototype, "filterPredicate", void 0);
+__decorate([property({
+	type: String,
+	attribute: `item-wrap`
+})], VerticalListElement.prototype, "itemWrap", void 0);
+__decorate([property({ attribute: false })], VerticalListElement.prototype, "checkboxRenderer", void 0);
+__decorate([property({
+	type: String,
+	attribute: `search-modes`,
+	reflect: true
+})], VerticalListElement.prototype, "searchModes", void 0);
+__decorate([property({
+	type: Boolean,
+	attribute: `items-draggable`,
+	reflect: true
+})], VerticalListElement.prototype, "itemsDraggable", void 0);
+__decorate([property({ attribute: false })], VerticalListElement.prototype, "dragPreviewRenderer", void 0);
+__decorate([property({ attribute: false })], VerticalListElement.prototype, "dragPreviewSource", void 0);
+__decorate([property({ attribute: false })], VerticalListElement.prototype, "items", void 0);
+__decorate([property({
+	type: String,
+	attribute: `key-property`
+})], VerticalListElement.prototype, "keyProperty", void 0);
+__decorate([property({ attribute: false })], VerticalListElement.prototype, "formatter", void 0);
+__decorate([property({ attribute: false })], VerticalListElement.prototype, "icon", void 0);
+__decorate([property({ attribute: false })], VerticalListElement.prototype, "iconColor", void 0);
+__decorate([property({ attribute: false })], VerticalListElement.prototype, "textColor", void 0);
+__decorate([property({ attribute: false })], VerticalListElement.prototype, "badge", void 0);
+__decorate([property({
+	type: Boolean,
+	attribute: `virtualize`,
+	reflect: true
+})], VerticalListElement.prototype, "virtualize", void 0);
+__decorate([property({
+	type: Number,
+	attribute: `item-height`
+})], VerticalListElement.prototype, "itemHeight", void 0);
+__decorate([property({
+	type: Boolean,
+	attribute: `items-droppable`,
+	reflect: true
+})], VerticalListElement.prototype, "itemsDroppable", void 0);
+__decorate([property({ attribute: false })], VerticalListElement.prototype, "editValidator", void 0);
+__decorate([property({ attribute: false })], VerticalListElement.prototype, "canDrop", void 0);
+VerticalListElement = __decorate([safeCustomElement(`ixfx-vertical-list`)], VerticalListElement);
+//#endregion
+export { VerticalListElement as t };