@ixfx/components 0.9.8 → 0.10.0

package/dist/vertical-list.js

@@ -2,14 +2,19 @@ import { t as TickledController } from "./tickled-controller-Dh1Uh_vG.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-C05WjbZh.js";
-import { t as ListNativeDragController } from "./list-native-drag-controller-B0hWdbtM.js";
+import { t as ListNativeDragController } from "./list-native-drag-controller-D97TYjn1.js";
 import { r as ListDragSelectController, t as ListSelectionController } from "./list-selection-controller-SA4piSBi.js";
 import { n as animateListItemIn, r as animateListItemOut } from "./list-item-animation-BUoEKi5s.js";
 import { LitElement, css, html, render } from "lit";
 import { property } from "lit/decorators.js";
 import { createCommandRegistry } from "@clinth/ui-commands";
 //#region src/vertical-list/vertical-list.ts
-const ITEM_SELECTOR = `li, [data-list-item]`;
+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;
 let VerticalListElement = class VerticalListElement extends LitElement {
 	constructor(..._args) {
 		super(..._args);
@@ -17,11 +22,24 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 		this.interactionMode = `standard`;
 		this.itemWrap = `stop`;
 		this.itemsDraggable = false;
+		this.keyProperty = ``;
+		this.virtualize = false;
+		this.itemHeight = 0;
 		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.selection = new ListSelectionController({
-			getOrderedItems: () => this._getVisibleItems(),
+			getOrderedItems: () => this.#selectionOrder(),
 			isSelectable: (el) => this._isCheckable(el),
 			getModes: () => ({
 				selectionMode: this.selectionMode,
@@ -63,6 +81,7 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 			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;
@@ -85,7 +104,7 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 		});
 		this.#dragSelect = new ListDragSelectController(this, {
 			getSurface: () => this.renderRoot.querySelector(`.container`),
-			isEnabled: () => this.selection.canDragSelect() && this._getVisibleItems().length > 0 && !this.hasAttribute(`disable-drag-select`),
+			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) => {
@@ -109,6 +128,14 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 			getLabel: (el) => el.getAttribute(`data-search-label`) ?? el.textContent?.trim() ?? ``,
 			highlightKey: `vertical-list-search`
 		}) });
+		this.#onScroll = () => {
+			if (!this.#virtualActive()) return;
+			if (this.#scrollRaf !== 0) return;
+			this.#scrollRaf = requestAnimationFrame(() => {
+				this.#scrollRaf = 0;
+				this.#syncVirtualWindow();
+			});
+		};
 		this._onPointerOver = (e) => {
 			const item = this._findListItem(e.composedPath());
 			if (item) this.tickled.handlePointerEnter(item);
@@ -176,10 +203,34 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 	}
 	#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;
+	#topSpacer;
+	#bottomSpacer;
+	/** Last measured viewport height — kept so a 0 read can't collapse the window. */
+	#lastViewportH;
+	#virtualWarned;
 	#nativeDragging;
 	#postDragSuppressTimer;
 	#nativeDrag;
@@ -250,9 +301,13 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 	}
 	#effectiveSearchModes() {
 		const raw = this.searchModes?.trim();
-		if (raw === void 0) return [...LIST_SEARCH_MODES];
-		const requested = new Set(raw.split(/\s+/));
-		return LIST_SEARCH_MODES.filter((m) => requested.has(m));
+		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;
@@ -273,6 +328,7 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 		this.#itemObserver.observe(this, { childList: true });
 		this.#searchRegistry ??= createCommandRegistry();
 		this.#syncSearchCommands();
+		this.#ensureResizeObserved();
 	}
 	disconnectedCallback() {
 		super.disconnectedCallback();
@@ -282,6 +338,12 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 		this.removeEventListener(`click`, this._onClick);
 		this.removeEventListener(`dblclick`, this._onDblClick);
 		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;
@@ -298,6 +360,10 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 	*/
 	#onItemsMutated(records) {
 		if (!this.isConnected) return;
+		if (this.#virtualActive()) {
+			this.#syncVirtualWindow(this.#reconcileRecords(records));
+			return;
+		}
 		const fresh = [];
 		for (const record of records) for (const node of record.addedNodes) {
 			if (!(node instanceof HTMLElement) || node.parentElement !== this) continue;
@@ -307,13 +373,43 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 			fresh.push(node);
 		}
 		if (fresh.length === 0) return;
-		const total = this.querySelectorAll(ITEM_SELECTOR).length;
-		if (fresh.length >= total) 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`)) && 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;
@@ -350,15 +446,28 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 		} 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();
 	}
 	/**
 	* 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.selection.deselect(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();
@@ -370,9 +479,15 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 	}
 	clearItems() {
 		this.#customWrappers.clear();
+		if (this.#virtualActive()) {
+			this.#allItems = [];
+			this.#pool = document.createDocumentFragment();
+			this.#pendingAnimate = [];
+		}
 		this.replaceChildren();
 		this.selection.reset();
 		this._syncItemStates();
+		if (this.#virtualActive()) this.#syncVirtualWindow(true);
 	}
 	/**
 	* Replace the entire item list in one call.
@@ -380,7 +495,16 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 	* Preserves `interactionMode` checkbox wrapping.
 	*/
 	setItems(items) {
-		this.clearItems();
+		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.#syncVirtualWindow(true);
+			return;
+		}
 		for (const item of items) this.appendChild(item);
 		if (this.interactionMode === `checked`) this._syncCheckboxes();
 	}
@@ -428,10 +552,23 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 	removeSelectedKeys(keys) {
 		this.selection.removeKeys(keys, (key) => this.#itemForKey(key));
 	}
-	/** Move the cursor to the item with this key and scroll it into view. */
+	/**
+	* 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) {
+				ul.scrollTop = index * this.itemHeight;
+				this.#syncVirtualWindow(true);
+			}
+		}
 		const el = this.#itemForKey(key);
-		if (!el) return;
+		if (!el || el.parentNode !== this) return;
 		this.tickled.focus(el);
 		el.scrollIntoView({
 			block: `nearest`,
@@ -439,25 +576,435 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 		});
 	}
 	#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);
+	}
+	/**
+	* 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 wanted = (el) => {
+		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`: return el.hasAttribute(`data-selected`);
-				case `checked`: return el.hasAttribute(`data-checked`);
-				case `either`: return el.hasAttribute(`data-selected`) || el.hasAttribute(`data-checked`);
+				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);
+			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 keyOf = (el) => el.getAttribute(`data-key`);
+		const previousKeys = new Set([...this.selection.selected].map(keyOf).filter((k) => k !== null));
+		const anchorKey = this.selection.anchor ? keyOf(this.selection.anchor) : null;
+		this.#customWrappers.clear();
+		this.replaceChildren(...source.map((item, index) => this.#createAdapterItem(item, index)));
+		if (previousKeys.size > 0 || anchorKey !== null) {
+			const next = [];
+			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 && key === anchorKey) anchor = el;
+			}
+			this.selection.seed(next, anchor);
+		}
+		if (this.interactionMode === `checked`) this._syncCheckboxes();
+		this._syncItemStates();
+		this._syncNativeDraggable();
+		this.#nativeDrag.refreshDraggable();
+	}
+	#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);
+		return li;
+	}
+	#fillAdapterItem(li, content, item) {
+		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.#stampAdapterKey(li, item);
+		this.#itemData.set(li, item);
+	}
+	/**
+	* 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 keyOf = (el) => el.getAttribute(`data-key`);
+		const previousKeys = new Set([...this.selection.selected].map(keyOf).filter((k) => k !== null));
+		const anchorKey = this.selection.anchor ? keyOf(this.selection.anchor) : null;
+		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);
+		if (previousKeys.size > 0 || anchorKey !== null) {
+			const next = [];
+			let anchor;
+			for (const el of this.#allItems) {
+				const key = keyOf(el);
+				if (key !== null && previousKeys.has(key)) next.push(el);
+				if (key !== null && key === anchorKey) anchor = el;
+			}
+			this.selection.seed(next, anchor);
+		}
+		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 = [];
+		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);
+				changed = true;
+			}
+		}
+		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();
+		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;
 		};
-		for (const el of this.querySelectorAll(ITEM_SELECTOR)) {
-			if (this.#wrappedElements.has(el)) continue;
-			if (el.hidden) continue;
-			if (wanted(el)) yield el;
+		this.#topSpacer = make();
+		this.#bottomSpacer = make();
+	}
+	#ensureResizeObserved() {
+		const ul = this.#scrollList();
+		if (!ul) return;
+		this.#resizeObserver ??= new ResizeObserver(() => {
+			this.#syncVirtualWindow();
+		});
+		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();
+		for (let i = start; i < end; i++) {
+			const el = this.#allItems[i];
+			if (el) this.#applyRowState(el);
+		}
+		const pending = this.#pendingAnimate;
+		this.#pendingAnimate = [];
+		for (const el of pending) {
+			this.#animatedItems.add(el);
+			if (el.parentNode === this) animateListItemIn(el);
 		}
 	}
+	/** Per-attach state the attached sweep can't cover (it only sees the window). */
+	#applyRowState(el) {
+		if (el instanceof HTMLElement) el.draggable = this.itemsDraggable && this._isCheckable(el);
+		el.removeAttribute(`data-marquee`);
+		el.removeAttribute(`data-drag-origin`);
+	}
+	/**
+	* 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();
+	}
 	_getVisibleItems() {
 		return Array.from(this.querySelectorAll(ITEM_SELECTOR)).filter((el) => {
 			if (this.#wrappedElements.has(el)) return false;
@@ -485,9 +1032,10 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 	_syncCheckboxes() {
 		const inCheckedMode = this.interactionMode === `checked`;
 		const wantsCustom = typeof this.checkboxRenderer === `function`;
-		if (inCheckedMode) for (const inner of Array.from(this.children)) {
+		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.parentElement !== this) continue;
+			if (inner.parentNode !== root) continue;
 			const wrapper = document.createElement(`li`);
 			wrapper.className = `ixfx-custom-row`;
 			const key = inner.getAttribute(`data-key`);
@@ -495,17 +1043,22 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 			if (key !== null) wrapper.setAttribute(`data-key`, key);
 			if (label !== null) wrapper.setAttribute(`data-search-label`, label);
 			inner.removeAttribute(`data-list-item`);
-			this.insertBefore(wrapper, inner);
+			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.parentElement !== this) continue;
+				if (wrapper.parentNode !== this && wrapper.parentNode !== this.#pool) continue;
 				inner.setAttribute(`data-list-item`, ``);
-				this.insertBefore(inner, wrapper);
+				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();
@@ -681,8 +1234,11 @@ let VerticalListElement = class VerticalListElement extends LitElement {
       outline: 1px solid transparent;
     }
 
-    /* Custom shadow-DOM components handle their own internal layout/padding */
-    ::slotted([data-list-item]) {
+    /* 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;
@@ -692,6 +1248,23 @@ let VerticalListElement = class VerticalListElement extends LitElement {
       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),
@@ -766,7 +1339,7 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 	render() {
 		return html`
       <div class="container">
-        <ul part="list">
+        <ul part="list" @scroll=${this.#onScroll}>
           <slot></slot>
         </ul>
         ${this.#marqueeRect ? html`<div class="marquee" part="marquee" style=${this.#marqueeStyle(this.#marqueeRect)}></div>` : ``}
@@ -800,6 +1373,22 @@ __decorate([property({
 	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({
+	type: Boolean,
+	attribute: `virtualize`,
+	reflect: true
+})], VerticalListElement.prototype, "virtualize", void 0);
+__decorate([property({
+	type: Number,
+	attribute: `item-height`
+})], VerticalListElement.prototype, "itemHeight", void 0);
 VerticalListElement = __decorate([safeCustomElement(`ixfx-vertical-list`)], VerticalListElement);
 //#endregion
 export { VerticalListElement };