@c2n/virtual-list 0.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nguyen Thai Vinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @c2n/virtual-list
+
+`<c2-virtual-list>` renders only the rows you can see. It windows `items` to the visible range plus an overscan
+margin, so 50 000 rows cost the same DOM as twenty — and every visible row is a real `c2-list-item`, so the markup,
+slots, selection styling and theming are the ones you already know from `c2-list`.
+
+```bash
+npm install @c2n/virtual-list
+```
+
+```html
+<c2-virtual-list
+  style="height: 320px"
+  aria-label="People"
+  searchable
+  highlight
+  selection="single"
+  item-key="id"
+  label-field="name"
+  description-field="team"
+></c2-virtual-list>
+```
+
+```js
+import '@c2n/virtual-list'
+
+const list = document.querySelector('c2-virtual-list')
+list.items = people
+list.addEventListener('selection-change', (event) => console.log(event.detail.value, event.detail.items))
+```
+
+- **Search** — `searchable` adds a field above the list; `search` is also a plain property, so an external input can
+  drive it. `search-fields` narrows what a query is matched against, `matcher` replaces the matching outright,
+  `min-search-length` and `search-debounce` tune when it runs, and `highlight` wraps what matched in `<mark>`.
+- **Sorting** — `sort="score:desc"`, or the `sort` property with an optional `comparator`, orders the rows.
+- **Selection** — `selection="single|multiple"` with `value` as the array of keys; ⌘/Ctrl-click toggles, shift-click
+  extends, ⌘/Ctrl-A selects everything. `item-key` decides identity.
+- **Async data** — set `dataSource` to `{ getItems({ start, count, search, sort }) }` and the list holds nothing: it
+  asks for one `block-size` block at a time as rows scroll into view, and hands the query and the sort to the server.
+  Rows whose block has not arrived render as skeletons.
+- **Keyboard and a11y** — the rows are a `listbox` of `option`s with a roving tab stop, `aria-posinset`/`aria-setsize`
+  (most rows are not in the DOM), arrow keys, Home/End, PageUp/PageDown and Enter/Space. Set `aria-label` on the host
+  to name the list.
+
+Give the host a height (or `--c2-virtual-list--max-height`). Windowing needs a **uniform** row height, which comes
+from `--c2-virtual-list__item--height` and is re-measured from the first rendered row; `item-height` is only the
+first-paint estimate. Two-line rows have to raise the variable.
+
+Theming is the usual `--c2-virtual-list__<part>--<property>` set: the root box, `search--*` and `search-field--*`
+(which drive the composed `c2-text-field`), `item--height`, `highlight--*`, `skeleton--*`,
+`state--*` and `footer--*`. Everything inside a row is themed through `c2-list-item`'s own variables.

package/dist/virtual-list.js

@@ -0,0 +1,688 @@
+import { LitElement, html, nothing, unsafeCSS } from "lit";
+import { property, query, state } from "lit/decorators.js";
+import { customElement } from "@c2n/core/element-helper.js";
+import { arrayPropertyConverter, jsonPropertyConverter } from "@c2n/core/lit-helper.js";
+import { defaultCompare, getFieldValue, sortEntryConverter } from "@c2n/core/data-helper.js";
+import { VirtualScrollController } from "@c2n/core/controllers/virtual-scroll.js";
+import "@c2n/list-item";
+import "@c2n/spinner";
+import "@c2n/text-field";
+//#region src/virtual-list.scss?inline
+var virtual_list_default = "/* ex : var((width: 24px), width, c2-checkbox)  returns var(--c2-checkbox-width, 24px) */\n:host {\n  display: flex;\n  flex-direction: column;\n  box-sizing: border-box;\n  min-height: 0;\n  overflow: hidden;\n  background: var(--c2-virtual-list--background,#ffffff);\n  color: var(--c2-virtual-list--color,#18181b);\n  font-size: var(--c2-virtual-list--font-size,14px);\n  max-height: var(--c2-virtual-list--max-height,none);\n  border-top: var(--c2-virtual-list--border-top);\n  border-right: var(--c2-virtual-list--border-right);\n  border-bottom: var(--c2-virtual-list--border-bottom);\n  border-left: var(--c2-virtual-list--border-left);\n  border-top-left-radius: var(--c2-virtual-list--border-top-left-radius,8px);\n  border-top-right-radius: var(--c2-virtual-list--border-top-right-radius,8px);\n  border-bottom-left-radius: var(--c2-virtual-list--border-bottom-left-radius,8px);\n  border-bottom-right-radius: var(--c2-virtual-list--border-bottom-right-radius,8px);\n  box-shadow: var(--c2-virtual-list--box-shadow);\n}\n\n:host([hidden]) {\n  display: none;\n}\n\n.search {\n  display: flex;\n  align-items: center;\n  gap: var(--c2-virtual-list__search--gap,8px);\n  flex: none;\n  background: var(--c2-virtual-list__search--background,transparent);\n  padding: var(--c2-virtual-list__search--padding,8px);\n  border-bottom: var(--c2-virtual-list__search--border-bottom,1px solid #e4e4e7);\n}\n\n.search[hidden] {\n  display: none;\n}\n\n.search-field {\n  flex: 1 1 auto;\n  min-width: 0;\n  --c2-text-field--background: var(--c2-virtual-list__search-field--background,#ffffff);\n  --c2-text-field--border-top: var(--c2-virtual-list__search-field--border,1px solid #e4e4e7);\n  --c2-text-field--border-right: var(--c2-virtual-list__search-field--border,1px solid #e4e4e7);\n  --c2-text-field--border-bottom: var(--c2-virtual-list__search-field--border,1px solid #e4e4e7);\n  --c2-text-field--border-left: var(--c2-virtual-list__search-field--border,1px solid #e4e4e7);\n  --c2-text-field--border-top-left-radius: var(--c2-virtual-list__search-field--border-radius,6px);\n  --c2-text-field--border-top-right-radius: var(--c2-virtual-list__search-field--border-radius,6px);\n  --c2-text-field--border-bottom-left-radius: var(--c2-virtual-list__search-field--border-radius,6px);\n  --c2-text-field--border-bottom-right-radius: var(--c2-virtual-list__search-field--border-radius,6px);\n  --c2-text-field--min-height: var(--c2-virtual-list__search-field--min-height,32px);\n}\n\n.viewport {\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow: auto;\n  overscroll-behavior: contain;\n  overflow-anchor: none;\n  padding: var(--c2-virtual-list__viewport--padding,4px);\n}\n\n.items {\n  display: flex;\n  flex-direction: column;\n}\n\n.item {\n  flex: none;\n  box-sizing: border-box;\n  height: var(--c2-virtual-list__item--height,36px);\n}\n\n.spacer {\n  flex: none;\n}\n\nmark {\n  background: var(--c2-virtual-list__highlight--background,#fef08a);\n  color: var(--c2-virtual-list__highlight--color,inherit);\n  font-weight: var(--c2-virtual-list__highlight--font-weight,600);\n  border-radius: var(--c2-virtual-list__highlight--border-radius,4px);\n}\n\n.skeleton {\n  display: block;\n  width: 60%;\n  height: 0.7em;\n  background: var(--c2-virtual-list__skeleton--background,#f4f4f5);\n  border-radius: var(--c2-virtual-list__skeleton--border-radius,4px);\n}\n\n.state {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  text-align: center;\n  color: var(--c2-virtual-list__state--color,#71717a);\n  padding: var(--c2-virtual-list__state--padding,32px 12px);\n  font-size: var(--c2-virtual-list__state--font-size,14px);\n}\n\n.state--error {\n  color: var(--c2-virtual-list__state__error--color,rgb(211, 21, 16));\n}\n\n.footer {\n  flex: none;\n  background: var(--c2-virtual-list__footer--background,transparent);\n  padding: var(--c2-virtual-list__footer--padding,8px 12px);\n  border-top: var(--c2-virtual-list__footer--border-top,1px solid #e4e4e7);\n}\n\n.footer[hidden] {\n  display: none;\n}";
+//#endregion
+//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/virtual-list.ts
+/** How long a typed run is treated as one typeahead query, matching `c2-list`. */
+var TYPEAHEAD_WINDOW = 600;
+/** Fields tried in order when no `label-field` is given, so a list of plain objects renders without configuration. */
+var IMPLICIT_LABEL_FIELDS = [
+	"label",
+	"name",
+	"title",
+	"value"
+];
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var VirtualList = class VirtualList extends LitElement {
+	constructor(..._args) {
+		super(..._args);
+		this.items = [];
+		this.itemKey = "";
+		this.labelField = "";
+		this.descriptionField = "";
+		this.disabledField = "";
+		this.searchable = false;
+		this.search = "";
+		this.searchFields = [];
+		this.minSearchLength = 1;
+		this.searchDebounce = 200;
+		this.searchPlaceholder = "Search";
+		this.highlight = false;
+		this.selection = "none";
+		this.value = [];
+		this.virtual = "auto";
+		this.itemHeight = 36;
+		this.overscan = 6;
+		this.virtualThreshold = 100;
+		this.blockSize = 100;
+		this.loading = false;
+		this.error = "";
+		this.emptyMessage = "No items";
+		this.noResultsMessage = "No matches";
+		this.hasToolbar = false;
+		this.hasFooter = false;
+		this.remoteTotal = -1;
+		this.focusedIndex = 0;
+		this.#visibleItems = [];
+		this.#blocks = /* @__PURE__ */ new Map();
+		this.#pendingBlocks = /* @__PURE__ */ new Set();
+		this.#measuredItemHeight = 0;
+		this.#selectedKeysSet = /* @__PURE__ */ new Set();
+		this.#selectionAnchor = -1;
+		this.#requestToken = 0;
+		this.#pendingFocus = false;
+		this.#pendingScrollTop = false;
+		this.#typeahead = "";
+		this.#virtualizer = new VirtualScrollController(this, {
+			scrollElement: () => this.viewport,
+			itemCount: () => this.itemCount,
+			itemHeight: () => this.#itemHeightPx,
+			overscan: () => this.overscan,
+			enabled: () => this.isVirtualized
+		});
+		this.#handleSearchInput = (event) => {
+			this.#scheduleSearch(event.target.value);
+		};
+		this.#handleSearchClear = () => {
+			clearTimeout(this.#searchTimer);
+			this.search = "";
+		};
+		this.#handleSearchKeyDown = (event) => {
+			if (event.key !== "ArrowDown" && event.key !== "Enter") return;
+			if (this.itemCount === 0) return;
+			event.preventDefault();
+			this.#moveFocus(this.focusedIndex);
+		};
+		this.#handleClick = (event) => {
+			const row = event.target?.closest?.("c2-list-item");
+			if (!(row instanceof HTMLElement) || !row.classList.contains("item")) return;
+			const index = Number(row.dataset.index);
+			if (!Number.isInteger(index)) return;
+			const item = this.#itemAt(index);
+			if (item === void 0 || this.#isDisabled(item)) return;
+			this.focusedIndex = index;
+			this.#activate(index, item, event.shiftKey, event.metaKey || event.ctrlKey);
+		};
+		this.#handleKeyDown = (event) => {
+			const count = this.itemCount;
+			if (count === 0) return;
+			if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "a" && this.selection === "multiple") {
+				event.preventDefault();
+				this.selectAll();
+				return;
+			}
+			const viewportRows = Math.max(1, Math.floor((this.viewport?.clientHeight ?? 0) / this.#itemHeightPx) - 1);
+			let index = this.focusedIndex;
+			switch (event.key) {
+				case "ArrowDown":
+					index = Math.min(count - 1, index + 1);
+					break;
+				case "ArrowUp":
+					index = Math.max(0, index - 1);
+					break;
+				case "Home":
+					index = 0;
+					break;
+				case "End":
+					index = count - 1;
+					break;
+				case "PageDown":
+					index = Math.min(count - 1, index + viewportRows);
+					break;
+				case "PageUp":
+					index = Math.max(0, index - viewportRows);
+					break;
+				case "Enter":
+				case " ": {
+					const item = this.#itemAt(index);
+					if (item === void 0 || this.#isDisabled(item)) return;
+					event.preventDefault();
+					this.#activate(index, item, event.shiftKey, event.metaKey || event.ctrlKey);
+					return;
+				}
+				default:
+					if (event.key.length === 1 && !event.metaKey && !event.ctrlKey && !event.altKey) {
+						event.preventDefault();
+						if (this.searchable) this.#typeIntoSearchField(event.key);
+						else this.#typeaheadTo(event.key);
+					}
+					return;
+			}
+			event.preventDefault();
+			this.#moveFocus(index);
+		};
+	}
+	static {
+		this.styles = unsafeCSS(virtual_list_default);
+	}
+	/** The items on show: `items` after search and sort. Empty while a `dataSource` is in charge. */
+	#visibleItems;
+	#blocks;
+	#pendingBlocks;
+	#measuredItemHeight;
+	/** `value` as a set, rebuilt only when the array identity changes, so a big selection costs one lookup per row. */
+	#selectedKeysOf;
+	#selectedKeysSet;
+	#selectionAnchor;
+	#requestToken;
+	#pendingFocus;
+	#pendingScrollTop;
+	#searchTimer;
+	#typeahead;
+	#typeaheadTimer;
+	#virtualizer;
+	/** Number of items on show right now: the filtered `items`, or the `dataSource` total for the current query. */
+	get itemCount() {
+		return this.dataSource ? Math.max(0, this.remoteTotal) : this.#visibleItems.length;
+	}
+	/** Whether the rows are currently windowed. */
+	get isVirtualized() {
+		if (this.virtual === "never") return false;
+		if (this.virtual === "always") return true;
+		return this.itemCount > this.virtualThreshold;
+	}
+	/** Whether a query is currently narrowing the list. */
+	get searching() {
+		return this.search.trim().length >= this.minSearchLength;
+	}
+	get #itemHeightPx() {
+		return this.#measuredItemHeight || this.itemHeight;
+	}
+	get #selectedKeys() {
+		if (this.#selectedKeysOf !== this.value) {
+			this.#selectedKeysOf = this.value;
+			this.#selectedKeysSet = new Set(this.value);
+		}
+		return this.#selectedKeysSet;
+	}
+	get #isBootstrapping() {
+		return Boolean(this.dataSource) && this.remoteTotal < 0 && !this.error;
+	}
+	/** The items currently selected. Only the loaded ones when a `dataSource` is used. */
+	getSelectedItems() {
+		const keys = this.#selectedKeys;
+		const selected = [];
+		for (let index = 0; index < this.itemCount; index++) {
+			const item = this.#itemAt(index);
+			if (item !== void 0 && keys.has(this.#keyAt(index, item))) selected.push(item);
+		}
+		return selected;
+	}
+	/** Selects every loaded item. Only meaningful with `selection="multiple"`. */
+	selectAll() {
+		if (this.selection !== "multiple") return;
+		const keys = [];
+		for (let index = 0; index < this.itemCount; index++) {
+			const item = this.#itemAt(index);
+			if (item !== void 0) keys.push(this.#keyAt(index, item));
+		}
+		this.#commitSelection(keys);
+	}
+	clearSelection() {
+		this.#commitSelection([]);
+	}
+	/** Scrolls the item at `index` into view, aligning it to the closest edge. */
+	scrollToIndex(index) {
+		this.#virtualizer.scrollToIndex(index);
+	}
+	/** Moves the roving focus to `index`, scrolling it into view first. */
+	focusItem(index) {
+		this.#moveFocus(index);
+	}
+	/**
+	* Re-reads the data. With a `dataSource` that drops every cached block and asks for the visible one again;
+	* otherwise it re-runs the search and the sort — which is what an `items` array mutated in place needs, since
+	* Lit only sees a new array.
+	*/
+	refresh() {
+		if (this.dataSource) {
+			this.#resetRemote();
+			return;
+		}
+		this.#rebuildVisibleItems();
+		this.requestUpdate();
+	}
+	disconnectedCallback() {
+		super.disconnectedCallback();
+		clearTimeout(this.#searchTimer);
+		clearTimeout(this.#typeaheadTimer);
+	}
+	willUpdate(changed) {
+		if (typeof this.value === "string") this.value = arrayPropertyConverter.fromAttribute(this.value);
+		if (typeof this.searchFields === "string") this.searchFields = arrayPropertyConverter.fromAttribute(this.searchFields);
+		const queryChanged = changed.has("search") || changed.has("minSearchLength");
+		const sortChanged = changed.has("sort") || changed.has("comparator");
+		if (this.dataSource) {
+			if (queryChanged || sortChanged || changed.has("dataSource")) this.#resetRemote();
+		} else if (queryChanged || sortChanged || changed.has("items") || changed.has("searchFields") || changed.has("matcher") || changed.has("labelField") || changed.has("descriptionField")) {
+			this.#rebuildVisibleItems();
+			if (queryChanged || sortChanged) this.#pendingScrollTop = true;
+		}
+		if (queryChanged && changed.get("search") !== void 0) this.dispatchEvent(new CustomEvent("search-change", {
+			bubbles: true,
+			composed: true,
+			detail: {
+				search: this.search,
+				matchCount: this.dataSource ? this.remoteTotal : this.#visibleItems.length
+			}
+		}));
+	}
+	updated(changed) {
+		super.updated(changed);
+		if (this.#pendingScrollTop) {
+			this.#pendingScrollTop = false;
+			if (this.viewport) this.viewport.scrollTop = 0;
+		}
+		this.#measureItemHeight();
+		if (this.#pendingFocus) {
+			const row = this.renderRoot.querySelector(".item[tabindex=\"0\"]");
+			if (row) {
+				this.#pendingFocus = false;
+				row.focus();
+			}
+		} else this.#syncFocusToWindow();
+		if (this.dataSource) this.#ensureBlocks();
+	}
+	render() {
+		const range = this.#virtualizer.range;
+		const count = this.itemCount;
+		const hasSearchBar = this.searchable || this.hasToolbar;
+		return html`
+      <div class="search" part="search" ?hidden=${!hasSearchBar}>
+        ${this.searchable ? html`<slot name="search">${this.#renderSearchField()}</slot>` : nothing}
+        <slot name="toolbar" @slotchange=${(event) => this.hasToolbar = this.#slotHasContent(event)}></slot>
+      </div>
+      <div class="viewport" part="viewport">
+        <div
+          class="items"
+          part="items"
+          role="listbox"
+          aria-multiselectable=${this.selection === "multiple" ? "true" : nothing}
+          aria-busy=${this.loading || this.#isBootstrapping ? "true" : "false"}
+          aria-label=${this.ariaLabel ?? "Items"}
+          @click=${this.#handleClick}
+          @keydown=${this.#handleKeyDown}
+        >
+          ${range.paddingTop > 0 ? html`<div class="spacer" role="presentation" style="height:${range.paddingTop}px"></div>` : nothing}
+          ${this.#renderRows(range.start, Math.min(range.end, count))}
+          ${range.paddingBottom > 0 ? html`<div class="spacer" role="presentation" style="height:${range.paddingBottom}px"></div>` : nothing}
+        </div>
+        ${this.#renderState(count)}
+      </div>
+      <div class="footer" part="footer" ?hidden=${!this.hasFooter}>
+        <slot name="footer" @slotchange=${(event) => this.hasFooter = this.#slotHasContent(event)}></slot>
+      </div>
+    `;
+	}
+	#renderSearchField() {
+		return html`
+      <c2-text-field
+        class="search-field"
+        type="search"
+        clearable
+        .value=${this.search}
+        placeholder=${this.searchPlaceholder}
+        aria-label=${this.searchPlaceholder}
+        @input=${this.#handleSearchInput}
+        @clear=${this.#handleSearchClear}
+        @keydown=${this.#handleSearchKeyDown}
+      ></c2-text-field>
+    `;
+	}
+	#renderState(count) {
+		if (this.error) return html`<div class="state state--error" part="state"><slot name="error">${this.error}</slot></div>`;
+		if (count > 0) return nothing;
+		if (this.loading || this.#isBootstrapping) return html`<div class="state" part="state">
+        <slot name="loading"><c2-spinner></c2-spinner></slot>
+      </div>`;
+		if (this.searching) return html`<div class="state" part="state"><slot name="no-results">${this.noResultsMessage}</slot></div>`;
+		return html`<div class="state" part="state"><slot name="empty">${this.emptyMessage}</slot></div>`;
+	}
+	#renderRows(start, end) {
+		const rows = [];
+		for (let index = start; index < end; index++) rows.push(this.#renderRow(index));
+		return rows;
+	}
+	#renderRow(index) {
+		const item = this.#itemAt(index);
+		if (item === void 0) return html`
+        <c2-list-item class="item" part="item" .applyContext=${true} .disabled=${true} aria-busy="true" data-index=${index}>
+          <span class="skeleton" part="skeleton"></span>
+        </c2-list-item>
+      `;
+		const key = this.#keyAt(index, item);
+		const selected = this.selection !== "none" && this.#selectedKeys.has(key);
+		const joinedBefore = selected && this.#isSelectedAt(index - 1);
+		const joinedAfter = selected && this.#isSelectedAt(index + 1);
+		return html`
+      <c2-list-item
+        class="item"
+        part=${`item${selected ? " item-selected" : ""}`}
+        data-index=${index}
+        ?joined-before=${joinedBefore}
+        ?joined-after=${joinedAfter}
+        .applyContext=${true}
+        .value=${key}
+        .data=${item}
+        .disabled=${this.#isDisabled(item)}
+        .selected=${selected}
+        tabindex=${index === this.focusedIndex ? 0 : -1}
+        aria-posinset=${index + 1}
+        aria-setsize=${this.itemCount}
+        >${this.#renderContent(item, index)}</c2-list-item
+      >
+    `;
+	}
+	#renderContent(item, index) {
+		if (this.renderItem) {
+			const context = {
+				item,
+				index,
+				search: this.search
+			};
+			return this.renderItem(context);
+		}
+		const description = this.descriptionField ? this.#textOf(getFieldValue(item, this.descriptionField)) : "";
+		return html`${this.#decorate(this.#labelOf(item))}${description ? html`<span slot="description">${this.#decorate(description)}</span>` : nothing}`;
+	}
+	/** Wraps every occurrence of the query in `<mark>`, so a match is visible without the reader hunting for it. */
+	#decorate(text) {
+		if (!this.highlight || !this.searching || !text) return text;
+		const query = this.search.trim();
+		const parts = text.split(new RegExp(`(${escapeRegExp(query)})`, "ig"));
+		if (parts.length === 1) return text;
+		return parts.map((part, index) => index % 2 === 1 ? html`<mark part="highlight">${part}</mark>` : part);
+	}
+	/** Search, then sort — the order a reader expects: they filter first and only then ask how it is ordered. */
+	#rebuildVisibleItems() {
+		const source = Array.isArray(this.items) ? this.items : [];
+		const next = this.searching ? source.filter((item) => this.#matches(item)) : source.slice();
+		this.#visibleItems = this.#applySort(next);
+	}
+	#matches(item) {
+		const query = this.search.trim().toLowerCase();
+		if (this.matcher) return this.matcher(item, query);
+		for (const value of this.#searchableValues(item)) if (value.toLowerCase().includes(query)) return true;
+		return false;
+	}
+	/** The strings a query is tested against: the declared fields, else the labelled ones, else everything scalar. */
+	#searchableValues(item) {
+		const fields = this.searchFields.length ? this.searchFields : [this.labelField, this.descriptionField].filter(Boolean);
+		if (fields.length) return fields.map((field) => this.#textOf(getFieldValue(item, field)));
+		if (item === null || typeof item !== "object") return [this.#textOf(item)];
+		return Object.values(item).filter((value) => typeof value === "string" || typeof value === "number").map((value) => String(value));
+	}
+	#applySort(items) {
+		const sort = this.sort;
+		if (!sort?.field) return items;
+		const compare = this.comparator ?? defaultCompare;
+		const direction = sort.direction === "desc" ? -1 : 1;
+		return items.sort((a, b) => direction * compare(getFieldValue(a, sort.field), getFieldValue(b, sort.field)));
+	}
+	#itemAt(index) {
+		if (!this.dataSource) return this.#visibleItems[index];
+		return this.#blocks.get(Math.floor(index / this.blockSize))?.[index % this.blockSize];
+	}
+	#keyAt(index, item) {
+		if (!this.itemKey) return String(index);
+		const key = getFieldValue(item, this.itemKey);
+		return key === void 0 || key === null ? String(index) : String(key);
+	}
+	/** Whether the row at `index` is selected — false for one a `dataSource` has not delivered, which cannot be. */
+	#isSelectedAt(index) {
+		if (index < 0 || index >= this.itemCount) return false;
+		const item = this.#itemAt(index);
+		return item !== void 0 && this.#selectedKeys.has(this.#keyAt(index, item));
+	}
+	#isDisabled(item) {
+		return this.disabledField ? Boolean(getFieldValue(item, this.disabledField)) : false;
+	}
+	#textOf(value) {
+		return value === void 0 || value === null ? "" : String(value);
+	}
+	/** A row's primary text: the declared field, the first conventional one, or the item itself for a list of strings. */
+	#labelOf(item) {
+		if (this.labelField) return this.#textOf(getFieldValue(item, this.labelField));
+		if (item === null || typeof item !== "object") return this.#textOf(item);
+		const record = item;
+		for (const field of IMPLICIT_LABEL_FIELDS) if (record[field] !== void 0) return this.#textOf(record[field]);
+		return "";
+	}
+	#resetRemote() {
+		this.#blocks.clear();
+		this.#pendingBlocks.clear();
+		this.#requestToken++;
+		this.remoteTotal = -1;
+		this.#pendingScrollTop = true;
+	}
+	/** Asks the source for whatever block the visible window needs and has not got. */
+	#ensureBlocks() {
+		const source = this.dataSource;
+		if (!source || this.error) return;
+		const range = this.#virtualizer.range;
+		const first = this.remoteTotal < 0 ? 0 : Math.floor(range.start / this.blockSize);
+		const last = this.remoteTotal < 0 ? 0 : Math.floor(Math.max(range.start, range.end - 1) / this.blockSize);
+		for (let block = first; block <= last; block++) {
+			if (this.#blocks.has(block) || this.#pendingBlocks.has(block)) continue;
+			this.#pendingBlocks.add(block);
+			const token = this.#requestToken;
+			source.getItems({
+				start: block * this.blockSize,
+				count: this.blockSize,
+				search: this.searching ? this.search.trim() : "",
+				sort: this.sort
+			}).then((result) => {
+				if (token !== this.#requestToken) return;
+				this.#blocks.set(block, result.items ?? []);
+				if (result.total !== void 0) this.remoteTotal = result.total;
+				else if (this.remoteTotal < 0) this.remoteTotal = (result.items ?? []).length;
+				this.requestUpdate();
+			}).catch((reason) => {
+				if (token !== this.#requestToken) return;
+				this.error = reason instanceof Error ? reason.message : String(reason);
+			}).finally(() => {
+				this.#pendingBlocks.delete(block);
+			});
+		}
+	}
+	#handleSearchInput;
+	#handleSearchClear;
+	#handleSearchKeyDown;
+	#scheduleSearch(next) {
+		clearTimeout(this.#searchTimer);
+		this.#searchTimer = setTimeout(() => {
+			this.search = next;
+		}, Math.max(0, this.searchDebounce));
+	}
+	/** Sends a character typed on the list to the search field, so typing anywhere in the component starts a search. */
+	#typeIntoSearchField(character) {
+		const field = this.searchFieldElement;
+		if (!field) return;
+		field.value = `${field.value}${character}`;
+		field.focus();
+		this.#scheduleSearch(field.value);
+	}
+	/** The `c2-list` behaviour for a list with no search field: jump to the next row whose label starts with the run. */
+	#typeaheadTo(character) {
+		clearTimeout(this.#typeaheadTimer);
+		this.#typeahead += character.toLowerCase();
+		this.#typeaheadTimer = setTimeout(() => this.#typeahead = "", TYPEAHEAD_WINDOW);
+		const count = this.itemCount;
+		const scan = Math.min(count, 2e3);
+		for (let step = 1; step <= scan; step++) {
+			const index = (this.focusedIndex + step) % count;
+			const item = this.#itemAt(index);
+			if (item === void 0) continue;
+			if (this.#labelOf(item).toLowerCase().startsWith(this.#typeahead)) {
+				this.#moveFocus(index);
+				return;
+			}
+		}
+	}
+	#handleClick;
+	#activate(index, item, range, additive) {
+		const key = this.#keyAt(index, item);
+		this.dispatchEvent(new CustomEvent("item-click", {
+			bubbles: true,
+			composed: true,
+			detail: {
+				item,
+				index,
+				key
+			}
+		}));
+		if (this.selection === "none") return;
+		if (this.selection === "single") {
+			this.#selectionAnchor = index;
+			this.#commitSelection([key]);
+			return;
+		}
+		if (range && this.#selectionAnchor >= 0) {
+			this.#commitSelection(this.#keysBetween(this.#selectionAnchor, index));
+			return;
+		}
+		this.#selectionAnchor = index;
+		if (additive) this.#commitSelection(this.value.includes(key) ? this.value.filter((entry) => entry !== key) : [...this.value, key]);
+		else this.#commitSelection([key]);
+	}
+	#keysBetween(from, to) {
+		const [start, end] = from <= to ? [from, to] : [to, from];
+		const keys = [];
+		for (let index = start; index <= end; index++) {
+			const item = this.#itemAt(index);
+			if (item !== void 0) keys.push(this.#keyAt(index, item));
+		}
+		return keys;
+	}
+	#commitSelection(next) {
+		if (next.length === this.value.length && next.every((key, index) => key === this.value[index])) return;
+		this.value = next;
+		this.dispatchEvent(new CustomEvent("selection-change", {
+			bubbles: false,
+			composed: true,
+			detail: {
+				value: [...next],
+				items: this.getSelectedItems()
+			}
+		}));
+	}
+	#handleKeyDown;
+	#moveFocus(index) {
+		const count = this.itemCount;
+		if (count === 0) return;
+		this.focusedIndex = Math.min(Math.max(index, 0), count - 1);
+		this.#pendingFocus = true;
+		this.#virtualizer.scrollToIndex(this.focusedIndex);
+	}
+	/**
+	* Keeps the roving tab stop inside the rendered window. Scrolling far away would otherwise leave no row with
+	* `tabindex="0"`, and the list would drop out of the tab order entirely.
+	*/
+	#syncFocusToWindow() {
+		const { start, end } = this.#virtualizer.range;
+		if (end <= start) return;
+		const clamped = Math.min(Math.max(this.focusedIndex, start), end - 1);
+		if (clamped === this.focusedIndex) return;
+		if (this.shadowRoot?.activeElement) this.#pendingFocus = true;
+		this.focusedIndex = clamped;
+	}
+	#measureItemHeight() {
+		const row = this.renderRoot.querySelector(".item");
+		if (!row) return;
+		const height = row.getBoundingClientRect().height;
+		if (height > 0 && Math.abs(height - this.#measuredItemHeight) > .01) {
+			this.#measuredItemHeight = height;
+			this.requestUpdate();
+		}
+	}
+	#slotHasContent(event) {
+		return event.target.assignedNodes({ flatten: true }).some((node) => node.nodeType !== Node.TEXT_NODE || Boolean(node.textContent?.trim()));
+	}
+};
+__decorate([query(".viewport")], VirtualList.prototype, "viewport", void 0);
+__decorate([query(".search-field")], VirtualList.prototype, "searchFieldElement", void 0);
+__decorate([property({ converter: jsonPropertyConverter })], VirtualList.prototype, "items", void 0);
+__decorate([property({
+	type: String,
+	attribute: "item-key"
+})], VirtualList.prototype, "itemKey", void 0);
+__decorate([property({
+	type: String,
+	attribute: "label-field"
+})], VirtualList.prototype, "labelField", void 0);
+__decorate([property({
+	type: String,
+	attribute: "description-field"
+})], VirtualList.prototype, "descriptionField", void 0);
+__decorate([property({
+	type: String,
+	attribute: "disabled-field"
+})], VirtualList.prototype, "disabledField", void 0);
+__decorate([property({ attribute: false })], VirtualList.prototype, "renderItem", void 0);
+__decorate([property({ attribute: false })], VirtualList.prototype, "matcher", void 0);
+__decorate([property({ attribute: false })], VirtualList.prototype, "comparator", void 0);
+__decorate([property({ attribute: false })], VirtualList.prototype, "dataSource", void 0);
+__decorate([property({ type: Boolean })], VirtualList.prototype, "searchable", void 0);
+__decorate([property({
+	type: String,
+	reflect: true
+})], VirtualList.prototype, "search", void 0);
+__decorate([property({
+	converter: arrayPropertyConverter,
+	attribute: "search-fields"
+})], VirtualList.prototype, "searchFields", void 0);
+__decorate([property({
+	type: Number,
+	attribute: "min-search-length"
+})], VirtualList.prototype, "minSearchLength", void 0);
+__decorate([property({
+	type: Number,
+	attribute: "search-debounce"
+})], VirtualList.prototype, "searchDebounce", void 0);
+__decorate([property({
+	type: String,
+	attribute: "search-placeholder"
+})], VirtualList.prototype, "searchPlaceholder", void 0);
+__decorate([property({ type: Boolean })], VirtualList.prototype, "highlight", void 0);
+__decorate([property({
+	converter: sortEntryConverter,
+	attribute: "sort",
+	reflect: true
+})], VirtualList.prototype, "sort", void 0);
+__decorate([property({ type: String })], VirtualList.prototype, "selection", void 0);
+__decorate([property({
+	converter: arrayPropertyConverter,
+	reflect: true
+})], VirtualList.prototype, "value", void 0);
+__decorate([property({ type: String })], VirtualList.prototype, "virtual", void 0);
+__decorate([property({
+	type: Number,
+	attribute: "item-height"
+})], VirtualList.prototype, "itemHeight", void 0);
+__decorate([property({ type: Number })], VirtualList.prototype, "overscan", void 0);
+__decorate([property({
+	type: Number,
+	attribute: "virtual-threshold"
+})], VirtualList.prototype, "virtualThreshold", void 0);
+__decorate([property({
+	type: Number,
+	attribute: "block-size"
+})], VirtualList.prototype, "blockSize", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], VirtualList.prototype, "loading", void 0);
+__decorate([property({ type: String })], VirtualList.prototype, "error", void 0);
+__decorate([property({
+	type: String,
+	attribute: "empty-message"
+})], VirtualList.prototype, "emptyMessage", void 0);
+__decorate([property({
+	type: String,
+	attribute: "no-results-message"
+})], VirtualList.prototype, "noResultsMessage", void 0);
+__decorate([state()], VirtualList.prototype, "hasToolbar", void 0);
+__decorate([state()], VirtualList.prototype, "hasFooter", void 0);
+__decorate([state()], VirtualList.prototype, "remoteTotal", void 0);
+__decorate([state()], VirtualList.prototype, "focusedIndex", void 0);
+VirtualList = __decorate([customElement("c2-virtual-list")], VirtualList);
+//#endregion
+export { VirtualList };

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@c2n/virtual-list",
+  "version": "0.0.7",
+  "type": "module",
+  "main": "dist/virtual-list.js",
+  "exports": {
+    ".": {
+      "types": "./types/src/virtual-list.d.ts",
+      "default": "./dist/virtual-list.js"
+    },
+    "./virtual-list-types.js": {
+      "types": "./types/src/virtual-list-types.d.ts",
+      "default": "./dist/virtual-list-types.js"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "default": "./react.js"
+    },
+    "./vue": {
+      "types": "./vue.d.ts",
+      "default": "./vue.js"
+    },
+    "./custom-elements.json": "./custom-elements.json"
+  },
+  "files": [
+    "dist",
+    "types",
+    "react.d.ts",
+    "react.js",
+    "vue.d.ts",
+    "vue.js"
+  ],
+  "keywords": [
+    "virtual-list",
+    "virtual scroll",
+    "virtualized",
+    "search",
+    "web component",
+    "lit"
+  ],
+  "license": "MIT",
+  "author": "code2nguyen@gmail.com",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/code2nguyen/web-components.git"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "wireit",
+    "build:only": "vite build",
+    "type-check": "wireit"
+  },
+  "wireit": {
+    "type-check": {
+      "dependencies": [
+        "../../core:build",
+        "../list-item:build",
+        "../text-field:build",
+        "../spinner:build"
+      ],
+      "command": "tsc -p tsconfig.lib.json --composite false"
+    },
+    "build": {
+      "dependencies": [
+        "type-check"
+      ],
+      "command": "vite build"
+    }
+  },
+  "dependencies": {
+    "@c2n/core": "0.0.7",
+    "@c2n/list-item": "0.0.7",
+    "@c2n/spinner": "0.0.7",
+    "@c2n/text-field": "0.0.7",
+    "lit": "3.3.3"
+  },
+  "devDependencies": {
+    "@c2n/config": "*"
+  },
+  "customElements": "custom-elements.json",
+  "gitHead": "c8db398a27f7cd417d665fdf5da455fee2d4e910"
+}

package/react.d.ts

@@ -0,0 +1,24 @@
+// GENERATED by @c2n/framework-types. Do not edit by hand.
+//
+// JSX types for the custom elements of @c2n/virtual-list. Import once, anywhere in the program:
+//
+//     import '@c2n/virtual-list/react'
+//
+// Register the elements at module scope before React renders, or React writes an object prop as an
+// attribute and it stringifies.
+
+import type { DetailedHTMLProps, HTMLAttributes } from 'react'
+import type { VirtualList } from '@c2n/virtual-list'
+
+/** Standard React host-element attributes plus the element's own public properties. */
+type C2Props<T> = DetailedHTMLProps<HTMLAttributes<T>, T> & Partial<Omit<T, keyof HTMLElement>>
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'c2-virtual-list': C2Props<VirtualList>
+    }
+  }
+}
+
+export {}

package/react.js

@@ -0,0 +1,3 @@
+// GENERATED by @c2n/framework-types. Do not edit by hand.
+// Types only — see the matching .d.ts.
+export {}

package/types/src/virtual-list-types.d.ts

@@ -0,0 +1,55 @@
+import type { SortEntry } from '@c2n/core/data-helper.js';
+export type { SortDirection, SortEntry } from '@c2n/core/data-helper.js';
+export type VirtualListSelectionMode = 'none' | 'single' | 'multiple';
+export type VirtualListVirtualMode = 'auto' | 'always' | 'never';
+export interface VirtualListItemContext {
+    /** The item being rendered. `undefined` while its `dataSource` block is still loading. */
+    item: unknown;
+    /** Index of the item in the list as it is shown — after search and sort. */
+    index: number;
+    /** The query the list is filtered by right now, so a renderer can highlight it itself. */
+    search: string;
+}
+/** Returns anything Lit can render: a `TemplateResult`, a string, a number, a node. */
+export type VirtualListItemRenderer = (context: VirtualListItemContext) => unknown;
+/** Decides whether an item survives the current query. Replaces the built-in field matching entirely. */
+export type VirtualListMatcher = (item: unknown, query: string) => boolean;
+export interface VirtualListItemsRequest {
+    /** Index of the first item requested. */
+    start: number;
+    /** Number of items requested. */
+    count: number;
+    /** The query the server should filter by. Empty when the list is not being searched. */
+    search: string;
+    /** The sort the server should apply. */
+    sort?: SortEntry;
+}
+export interface VirtualListItemsResult {
+    items: unknown[];
+    /** Total number of items on the server *for this query*. Required on the first response so the scrollbar can be sized. */
+    total?: number;
+}
+/**
+ * Lazy item source: the list asks for one block of items at a time as they scroll into view, instead of holding the
+ * whole dataset in `items`. Searching and sorting are delegated to the source.
+ */
+export interface VirtualListDataSource {
+    getItems(request: VirtualListItemsRequest): Promise<VirtualListItemsResult>;
+}
+export interface VirtualListSelectionChangeEventDetail {
+    /** Keys of the selected items (`item-key` field, or the item index when no `item-key` is set). */
+    value: string[];
+    /** The selected items themselves; only the loaded ones when a `dataSource` is used. */
+    items: unknown[];
+}
+export interface VirtualListItemEventDetail {
+    item: unknown;
+    index: number;
+    key: string;
+}
+export interface VirtualListSearchChangeEventDetail {
+    search: string;
+    /** How many items match, or `-1` while a `dataSource` has not reported a total yet. */
+    matchCount: number;
+}
+//# sourceMappingURL=virtual-list-types.d.ts.map

package/types/src/virtual-list-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-list-types.d.ts","sourceRoot":"","sources":["../../src/virtual-list-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAEzD,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAExE,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAA;AACrE,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;AAEhE,MAAM,WAAW,sBAAsB;IACrC,0FAA0F;IAC1F,IAAI,EAAE,OAAO,CAAA;IACb,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAA;IACb,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAA;CACf;AAED,uFAAuF;AACvF,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAA;AAElF,yGAAyG;AACzG,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAA;AAE1E,MAAM,WAAW,uBAAuB;IACtC,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,wFAAwF;IACxF,MAAM,EAAE,MAAM,CAAA;IACd,wCAAwC;IACxC,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,EAAE,CAAA;IAChB,0HAA0H;IAC1H,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAA;CAC5E;AAED,MAAM,WAAW,qCAAqC;IACpD,kGAAkG;IAClG,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,uFAAuF;IACvF,KAAK,EAAE,OAAO,EAAE,CAAA;CACjB;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,kCAAkC;IACjD,MAAM,EAAE,MAAM,CAAA;IACd,uFAAuF;IACvF,UAAU,EAAE,MAAM,CAAA;CACnB"}

package/types/src/virtual-list.d.ts

@@ -0,0 +1,218 @@
+import { LitElement, type PropertyValues, type TemplateResult } from 'lit';
+import type { TypedAddEventListener, TypedRemoveEventListener } from '@c2n/core/event-helper.js';
+import { type SortEntry } from '@c2n/core/data-helper.js';
+import type { VirtualListDataSource, VirtualListItemEventDetail, VirtualListItemRenderer, VirtualListMatcher, VirtualListSearchChangeEventDetail, VirtualListSelectionChangeEventDetail, VirtualListSelectionMode, VirtualListVirtualMode } from './virtual-list-types.js';
+import '@c2n/list-item';
+import '@c2n/spinner';
+import '@c2n/text-field';
+/** Events fired by {@link VirtualList}, keyed for `addEventListener`. */
+export interface VirtualListEventMap {
+    'selection-change': CustomEvent<VirtualListSelectionChangeEventDetail>;
+    'item-click': CustomEvent<VirtualListItemEventDetail>;
+    'search-change': CustomEvent<VirtualListSearchChangeEventDetail>;
+}
+export interface VirtualList {
+    addEventListener: TypedAddEventListener<VirtualList, VirtualListEventMap>;
+    removeEventListener: TypedRemoveEventListener<VirtualList, VirtualListEventMap>;
+}
+/**
+ * A long list that only renders what you can see. It windows `items` to the visible range plus an overscan margin with
+ * the same `VirtualScrollController` the data grid uses, so 50 000 rows cost the same DOM as 20, and it renders every
+ * visible row as a real `c2-list-item` — the same markup, slots, selection styling and theme as `c2-list`.
+ *
+ * ```html
+ * <c2-virtual-list
+ *   style="height: 320px"
+ *   searchable
+ *   highlight
+ *   selection="single"
+ *   item-key="id"
+ *   label-field="name"
+ *   description-field="team"
+ * ></c2-virtual-list>
+ * <script type="module">
+ *   document.querySelector('c2-virtual-list').items = people
+ * </script>
+ * ```
+ *
+ * **Give the host a height** (or `--c2-virtual-list--max-height`) — the list scrolls inside it.
+ *
+ * **Uniform item height.** Windowing needs every row to be the same height. The height comes from
+ * `--c2-virtual-list__item--height` and is re-measured from the first rendered row, so a theme change is picked up;
+ * `item-height` is only the estimate used for the first paint. A list with two-line rows must raise the variable.
+ *
+ * A run of adjacent selected rows squares the corners between them, so it reads as one block rather than a stack of
+ * separate pills — the same `joined-before` / `joined-after` contract `c2-list` uses.
+ *
+ * **Search.** `searchable` adds a search field above the list; `search` is also a plain property, so an external input
+ * can drive it instead. Matching runs over `search-fields` (falling back to `label-field` and `description-field`, then
+ * to every string value of the item), and `matcher` replaces that logic outright. `highlight` wraps the matched text in
+ * `<mark>`. With a `dataSource` the query is sent to the server instead and the local matcher is never used.
+ *
+ * Set `aria-label` on the host to name the list; it is mirrored onto the inner `role="listbox"`, which falls back to
+ * `Items`.
+ *
+ * @tag c2-virtual-list
+ *
+ * @slot search - Replaces the built-in search field. Set `search` yourself from its events.
+ * @slot toolbar - Extra controls beside the search field, for a filter chip or a count. Hidden when empty.
+ * @slot footer - Bar below the list, for a total or a pager. Hidden when empty.
+ * @slot empty - Replaces the built-in "no items" message.
+ * @slot no-results - Replaces the built-in "no matches" message shown while a search is active.
+ * @slot loading - Replaces the built-in spinner shown while the first items load.
+ * @slot error - Replaces the built-in message shown when `error` is set.
+ *
+ * @internalcomponent c2-list-item
+ * @internalcomponent c2-text-field
+ * @internalcomponent c2-spinner
+ *
+ * @event {CustomEvent<VirtualListSelectionChangeEventDetail>} selection-change - Fired after the user changes the selection. `detail.value` is the array of selected keys, `detail.items` the matching items. Does not bubble: several components fire `selection-change`, so a listener belongs on the element itself rather than on an ancestor.
+ * @event {CustomEvent<VirtualListItemEventDetail>} item-click - Fired when a row is clicked, before the selection is applied.
+ * @event {CustomEvent<VirtualListSearchChangeEventDetail>} search-change - Fired after the query settles, with the number of items that match.
+ *
+ * @cssproperty {color} [--c2-virtual-list--background=#ffffff]
+ * @cssproperty {color} [--c2-virtual-list--color=#18181b]
+ * @cssproperty {font-size} [--c2-virtual-list--font-size=14px]
+ * @cssproperty {pixel} [--c2-virtual-list--max-height=none] - Caps the height when the host is not sized itself; the list scrolls.
+ *
+ * @cssproperty {border} --c2-virtual-list--border-top
+ * @cssproperty {border} --c2-virtual-list--border-right
+ * @cssproperty {border} --c2-virtual-list--border-bottom
+ * @cssproperty {border} --c2-virtual-list--border-left
+ *
+ * @cssproperty {border-radius} [--c2-virtual-list--border-top-left-radius=8px]
+ * @cssproperty {border-radius} [--c2-virtual-list--border-top-right-radius=8px]
+ * @cssproperty {border-radius} [--c2-virtual-list--border-bottom-left-radius=8px]
+ * @cssproperty {border-radius} [--c2-virtual-list--border-bottom-right-radius=8px]
+ *
+ * @cssproperty {box-shadow} --c2-virtual-list--box-shadow
+ *
+ * @cssproperty {color} [--c2-virtual-list__search--background=transparent]
+ * @cssproperty {padding} [--c2-virtual-list__search--padding=8px]
+ * @cssproperty {pixel} [--c2-virtual-list__search--gap=8px]
+ * @cssproperty {border} [--c2-virtual-list__search--border-bottom=1px solid #e4e4e7]
+ *
+ * @cssproperty {color} [--c2-virtual-list__search-field--background=#ffffff] - Themes the built-in `c2-text-field`.
+ * @cssproperty {border} [--c2-virtual-list__search-field--border=1px solid #e4e4e7]
+ * @cssproperty {border-radius} [--c2-virtual-list__search-field--border-radius=6px]
+ * @cssproperty {pixel} [--c2-virtual-list__search-field--min-height=32px]
+ *
+ * @cssproperty {pixel} [--c2-virtual-list__viewport--padding=4px]
+ *
+ * @cssproperty {pixel} [--c2-virtual-list__item--height=36px] - Row height; windowing needs it uniform.
+ *
+ *
+ * @cssproperty {color} [--c2-virtual-list__highlight--background=#fef08a]
+ * @cssproperty {color} [--c2-virtual-list__highlight--color=inherit]
+ * @cssproperty {font-weight} [--c2-virtual-list__highlight--font-weight=600]
+ * @cssproperty {border-radius} [--c2-virtual-list__highlight--border-radius=4px]
+ *
+ * @cssproperty {color} [--c2-virtual-list__skeleton--background=#f4f4f5] - Placeholder shown in rows whose `dataSource` block is still loading.
+ * @cssproperty {border-radius} [--c2-virtual-list__skeleton--border-radius=4px]
+ *
+ * @cssproperty {color} [--c2-virtual-list__state--color=#71717a] - Colour of the empty, no-results and loading messages.
+ * @cssproperty {padding} [--c2-virtual-list__state--padding=32px 12px]
+ * @cssproperty {font-size} [--c2-virtual-list__state--font-size=14px]
+ * @cssproperty {color} [--c2-virtual-list__state__error--color=rgb(211, 21, 16)]
+ *
+ * @cssproperty {color} [--c2-virtual-list__footer--background=transparent]
+ * @cssproperty {padding} [--c2-virtual-list__footer--padding=8px 12px]
+ * @cssproperty {border} [--c2-virtual-list__footer--border-top=1px solid #e4e4e7]
+ */
+export declare class VirtualList extends LitElement {
+    #private;
+    static styles: import("lit").CSSResult;
+    private viewport;
+    private searchFieldElement;
+    /** The items to display. An array in the property, JSON in the attribute. */
+    items: unknown[];
+    /** Field used as the identity of an item, for selection and typeahead. Falls back to the item index. */
+    itemKey: string;
+    /** Field read for a row's primary text. Defaults to `label`, `name`, `title` or `value`, then the item itself. */
+    labelField: string;
+    /** Field read for a row's second, muted line. */
+    descriptionField: string;
+    /** Field whose truthy value makes a row unselectable. */
+    disabledField: string;
+    /** Renders a row's content, replacing the label/description pair. */
+    renderItem?: VirtualListItemRenderer;
+    /** Replaces the built-in field matching while searching. */
+    matcher?: VirtualListMatcher;
+    /** Client-side sort comparator for the `sort` field's values. */
+    comparator?: (a: unknown, b: unknown) => number;
+    /** Lazy item source used instead of `items`; the list requests one block at a time as rows scroll into view. */
+    dataSource?: VirtualListDataSource;
+    /** Shows the built-in search field above the list. */
+    searchable: boolean;
+    /** The query the list is filtered by. Set by the built-in field, or from outside. */
+    search: string;
+    /** Fields the query is matched against: an array in the property, `;`-separated in the attribute. */
+    searchFields: string[];
+    /** Queries shorter than this are ignored, so the list is not filtered on the first keystroke. */
+    minSearchLength: number;
+    /** Milliseconds the built-in field waits after the last keystroke before the query is applied. */
+    searchDebounce: number;
+    /** Placeholder of the built-in search field. */
+    searchPlaceholder: string;
+    /** Wraps the matched part of a row's text in `<mark part="highlight">`. */
+    highlight: boolean;
+    /** The sort: `SortEntry` in the property, `field:asc` in the `sort` attribute. */
+    sort?: SortEntry;
+    /** `single` selects one row at a time, `multiple` supports ⌘/ctrl-click and shift-click ranges. */
+    selection: VirtualListSelectionMode;
+    /** Keys of the selected items: an array in the property, `;`-separated in the attribute. */
+    value: string[];
+    /** `auto` windows past `virtual-threshold` items; `always` and `never` force it. */
+    virtual: VirtualListVirtualMode;
+    /** Item height in pixels used before the first row has been measured. */
+    itemHeight: number;
+    /** Rows rendered above and below the viewport while windowing. */
+    overscan: number;
+    /** Item count past which `virtual="auto"` starts windowing. */
+    virtualThreshold: number;
+    /** Number of items the list asks a `dataSource` for at a time. */
+    blockSize: number;
+    /** Shows the loading state; implied while a `dataSource` resolves its first block. */
+    loading: boolean;
+    /** Shows the error state with this message. */
+    error: string;
+    /** Message shown when there are no items at all. */
+    emptyMessage: string;
+    /** Message shown when a search is active and nothing matches. */
+    noResultsMessage: string;
+    private hasToolbar;
+    private hasFooter;
+    private remoteTotal;
+    private focusedIndex;
+    /** Number of items on show right now: the filtered `items`, or the `dataSource` total for the current query. */
+    get itemCount(): number;
+    /** Whether the rows are currently windowed. */
+    get isVirtualized(): boolean;
+    /** Whether a query is currently narrowing the list. */
+    get searching(): boolean;
+    /** The items currently selected. Only the loaded ones when a `dataSource` is used. */
+    getSelectedItems(): unknown[];
+    /** Selects every loaded item. Only meaningful with `selection="multiple"`. */
+    selectAll(): void;
+    clearSelection(): void;
+    /** Scrolls the item at `index` into view, aligning it to the closest edge. */
+    scrollToIndex(index: number): void;
+    /** Moves the roving focus to `index`, scrolling it into view first. */
+    focusItem(index: number): void;
+    /**
+     * Re-reads the data. With a `dataSource` that drops every cached block and asks for the visible one again;
+     * otherwise it re-runs the search and the sort — which is what an `items` array mutated in place needs, since
+     * Lit only sees a new array.
+     */
+    refresh(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    protected updated(changed: PropertyValues): void;
+    render(): TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'c2-virtual-list': VirtualList;
+    }
+}
+//# sourceMappingURL=virtual-list.d.ts.map

package/types/src/virtual-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-list.d.ts","sourceRoot":"","sources":["../../src/virtual-list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA4B,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAA;AAGpG,OAAO,KAAK,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AAGhG,OAAO,EAAqD,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAE5G,OAAO,KAAK,EACV,qBAAqB,EAErB,0BAA0B,EAC1B,uBAAuB,EACvB,kBAAkB,EAClB,kCAAkC,EAClC,qCAAqC,EACrC,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,gBAAgB,CAAA;AACvB,OAAO,cAAc,CAAA;AACrB,OAAO,iBAAiB,CAAA;AAaxB,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IAClC,kBAAkB,EAAE,WAAW,CAAC,qCAAqC,CAAC,CAAA;IACtE,YAAY,EAAE,WAAW,CAAC,0BAA0B,CAAC,CAAA;IACrD,eAAe,EAAE,WAAW,CAAC,kCAAkC,CAAC,CAAA;CACjE;AAED,MAAM,WAAW,WAAW;IAC1B,gBAAgB,EAAE,qBAAqB,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAAA;IACzE,mBAAmB,EAAE,wBAAwB,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAAA;CAChF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuGG;AACH,qBACa,WAAY,SAAQ,UAAU;;IACzC,OAAgB,MAAM,0BAAoB;IAEtB,OAAO,CAAC,QAAQ,CAAqB;IACjC,OAAO,CAAC,kBAAkB,CAAmB;IAErE,6EAA6E;IAC7B,KAAK,EAAE,OAAO,EAAE,CAAK;IAErE,wGAAwG;IACrD,OAAO,SAAK;IAE/D,kHAAkH;IAC5D,UAAU,SAAK;IAErE,iDAAiD;IACW,gBAAgB,SAAK;IAEjF,yDAAyD;IACA,aAAa,SAAK;IAE3E,qEAAqE;IACrC,UAAU,CAAC,EAAE,uBAAuB,CAAA;IAEpE,4DAA4D;IAC5B,OAAO,CAAC,EAAE,kBAAkB,CAAA;IAE5D,iEAAiE;IACjC,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,KAAK,MAAM,CAAA;IAE/E,gHAAgH;IAChF,UAAU,CAAC,EAAE,qBAAqB,CAAA;IAElE,sDAAsD;IACzB,UAAU,UAAQ;IAE/C,qFAAqF;IAC1C,MAAM,SAAK;IAEtD,qGAAqG;IACxB,YAAY,EAAE,MAAM,EAAE,CAAK;IAExG,iGAAiG;IACrC,eAAe,SAAI;IAE/E,kGAAkG;IACxC,cAAc,SAAM;IAE9E,gDAAgD;IACa,iBAAiB,SAAW;IAEzF,2EAA2E;IAC9C,SAAS,UAAQ;IAE9C,kFAAkF;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAE/F,mGAAmG;IACvE,SAAS,EAAE,wBAAwB,CAAS;IAExE,4FAA4F;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAK;IAEpF,oFAAoF;IACxD,OAAO,EAAE,sBAAsB,CAAS;IAEpE,yEAAyE;IACnB,UAAU,SAAK;IAErE,kEAAkE;IACtC,QAAQ,SAAI;IAExC,+DAA+D;IACH,gBAAgB,SAAM;IAElF,kEAAkE;IACb,SAAS,SAAM;IAEpE,sFAAsF;IAC1C,OAAO,UAAQ;IAE3D,+CAA+C;IACnB,KAAK,SAAK;IAEtC,oDAAoD;IACI,YAAY,SAAa;IAEjF,iEAAiE;IACJ,gBAAgB,SAAe;IAEnF,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,YAAY,CAAI;IA0BjC,gHAAgH;IAChH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,+CAA+C;IAC/C,IAAI,aAAa,IAAI,OAAO,CAI3B;IAED,uDAAuD;IACvD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAkBD,sFAAsF;IACtF,gBAAgB,IAAI,OAAO,EAAE;IAU7B,8EAA8E;IAC9E,SAAS;IAUT,cAAc;IAId,8EAA8E;IAC9E,aAAa,CAAC,KAAK,EAAE,MAAM;IAI3B,uEAAuE;IACvE,SAAS,CAAC,KAAK,EAAE,MAAM;IAIvB;;;;OAIG;IACH,OAAO;IASE,oBAAoB;cAMV,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC;cAmCxC,OAAO,CAAC,OAAO,EAAE,cAAc;IAoBzC,MAAM;CAschB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,iBAAiB,EAAE,WAAW,CAAA;KAC/B;CACF"}

package/vue.d.ts

@@ -0,0 +1,48 @@
+// GENERATED by @c2n/framework-types. Do not edit by hand.
+//
+// Vue template types for the custom elements of @c2n/virtual-list. Import once, anywhere in the program:
+//
+//     import '@c2n/virtual-list/vue'
+//
+// Tell the compiler about the tags as well, or every c2-* tag is resolved as a Vue component and renders
+// nothing: template.compilerOptions.isCustomElement = (tag) => tag.startsWith('c2-') in vite.config.ts.
+
+import type { DefineComponent, HTMLAttributes } from 'vue'
+import type { VirtualList, VirtualListEventMap } from '@c2n/virtual-list'
+
+/** The element's own public properties, plus every attribute Vue understands on a host element. */
+type C2Props<T> = Partial<Omit<T, keyof HTMLElement>> & HTMLAttributes
+
+declare module 'vue' {
+  interface GlobalComponents {
+    'c2-virtual-list': DefineComponent<
+      C2Props<VirtualList> & {
+        'item-key'?: unknown
+        'label-field'?: unknown
+        'description-field'?: unknown
+        'disabled-field'?: unknown
+        'search-fields'?: unknown
+        'min-search-length'?: unknown
+        'search-debounce'?: unknown
+        'search-placeholder'?: unknown
+        'item-height'?: unknown
+        'virtual-threshold'?: unknown
+        'block-size'?: unknown
+        'empty-message'?: unknown
+        'no-results-message'?: unknown
+        onSearchChange?: (event: VirtualListEventMap['search-change']) => void
+        onItemClick?: (event: VirtualListEventMap['item-click']) => void
+        onSelectionChange?: (event: VirtualListEventMap['selection-change']) => void
+      }
+    >
+  }
+}
+
+declare module '@vue/runtime-dom' {
+  interface HTMLAttributes {
+    /** Vue's own definition omits it, and slotting a plain element into a component needs it. */
+    slot?: string
+  }
+}
+
+export {}

package/vue.js

@@ -0,0 +1,3 @@
+// GENERATED by @c2n/framework-types. Do not edit by hand.
+// Types only — see the matching .d.ts.
+export {}