forge-select 0.4.0 → 0.6.0

package/dist/index.js

@@ -156,6 +156,95 @@ function normalizeRemoteResult(ajax, response) {
   return { options: result.options, hasMore: ajax.pagination ? Boolean(result.hasMore) : false };
 }
 
+// src/remote-cache.ts
+var REMOTE_CACHE_LIMIT = 50;
+var RemoteCache = class {
+  constructor() {
+    this.entries = /* @__PURE__ */ new Map();
+  }
+  get(key, now = Date.now()) {
+    const entry = this.entries.get(key);
+    if (!entry) return void 0;
+    if (entry.expiresAt <= now) {
+      this.entries.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  set(key, value, ttl, now = Date.now()) {
+    if (ttl <= 0) return;
+    if (this.entries.size >= REMOTE_CACHE_LIMIT && !this.entries.has(key)) {
+      const oldest = this.entries.keys().next().value;
+      this.entries.delete(oldest);
+    }
+    this.entries.set(key, { value, expiresAt: now + ttl });
+  }
+  clear() {
+    this.entries.clear();
+  }
+};
+
+// src/search.ts
+function normalizeSearchText(value, accentInsensitive = true) {
+  const lower = value.toLocaleLowerCase();
+  return accentInsensitive ? lower.normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/đ/g, "d") : lower;
+}
+function getSearchField(option, field) {
+  if (field === "label") return option.label;
+  if (field === "description") return option.description ?? "";
+  const path = field.slice(5).split(".");
+  let value = option.meta;
+  for (const key of path) {
+    if (!value || typeof value !== "object") return "";
+    value = value[key];
+  }
+  return value == null ? "" : String(value);
+}
+var SearchIndex = class {
+  constructor() {
+    this.cache = /* @__PURE__ */ new WeakMap();
+  }
+  clear() {
+    this.cache = /* @__PURE__ */ new WeakMap();
+  }
+  score(option, query, config) {
+    const normalizedQuery = normalizeSearchText(query.trim(), config.accentInsensitive);
+    if (!normalizedQuery) return 1;
+    if (config.scorer) return config.scorer(option, query.trim(), normalizedQuery);
+    const key = `${config.accentInsensitive ? "1" : "0"}:${config.fields.join("\0")}`;
+    let variants = this.cache.get(option);
+    if (!variants) {
+      variants = /* @__PURE__ */ new Map();
+      this.cache.set(option, variants);
+    }
+    let haystacks = variants.get(key);
+    if (!haystacks) {
+      haystacks = config.fields.map(
+        (field) => normalizeSearchText(getSearchField(option, field), config.accentInsensitive)
+      );
+      variants.set(key, haystacks);
+    }
+    const tokens = config.tokenSearch ? normalizedQuery.split(/\s+/).filter(Boolean) : [normalizedQuery];
+    if (!tokens.every((token) => haystacks.some((field) => field.includes(token)))) return 0;
+    const label = haystacks[config.fields.indexOf("label")];
+    if (label === normalizedQuery) return 4;
+    if (label?.startsWith(normalizedQuery)) return 3;
+    if (label?.includes(normalizedQuery)) return 2;
+    return 1;
+  }
+};
+function findNormalizedRanges(label, query, accentInsensitive = true) {
+  const tokens = normalizeSearchText(query.trim(), accentInsensitive).split(/\s+/).filter(Boolean);
+  if (!tokens.length) return [];
+  const normalized = normalizeSearchText(label, accentInsensitive);
+  const ranges = [];
+  for (const token of tokens) {
+    const index = normalized.indexOf(token);
+    if (index >= 0) ranges.push([index, index + token.length]);
+  }
+  return ranges.sort((a, b) => a[0] - b[0]);
+}
+
 // src/selection.ts
 function isGroup(item) {
   return item.options !== void 0;
@@ -222,6 +311,8 @@ var DEFAULT_ITEM_HEIGHT = 36;
 var VIRTUAL_BUFFER = 5;
 var VIRTUAL_THRESHOLD = 100;
 var ROW_CACHE_LIMIT = 2e3;
+var PAGE_SIZE = 10;
+var TYPEAHEAD_RESET_MS = 500;
 var uidCounter = 0;
 var ForgeSelect = class {
   constructor(target, options = {}) {
@@ -239,7 +330,14 @@ var ForgeSelect = class {
     this.rows = [];
     this.navItems = [];
     this.highlightedIndex = -1;
+    this.typeaheadBuffer = "";
+    this.typeaheadTimer = null;
     this.rowContentCache = /* @__PURE__ */ new Map();
+    this.rowHeightCache = /* @__PURE__ */ new Map();
+    this.rowOffsetsCache = null;
+    this.scrollRafId = null;
+    this.ancestorScrollRafId = null;
+    this.searchIndex = new SearchIndex();
     this.expandedValues = /* @__PURE__ */ new Set();
     this.loading = false;
     this.loadingMore = false;
@@ -249,6 +347,7 @@ var ForgeSelect = class {
     this.ajaxRequestId = 0;
     this.ajaxController = null;
     this.remoteLoaded = false;
+    this.remoteCache = new RemoteCache();
     this.loadError = null;
     this.originalDisplay = "";
     this.originalDisabled = false;
@@ -266,7 +365,12 @@ var ForgeSelect = class {
       this.positionDropdown();
     };
     this.onAncestorScroll = () => {
-      if (this.portalHost) this.positionDropdown();
+      if (!this.portalHost) return;
+      if (this.ancestorScrollRafId != null) return;
+      this.ancestorScrollRafId = requestAnimationFrame(() => {
+        this.ancestorScrollRafId = null;
+        this.positionDropdown();
+      });
     };
     this.onNativeInvalid = (event) => {
       event.preventDefault();
@@ -274,6 +378,7 @@ var ForgeSelect = class {
       this.control.setAttribute("aria-invalid", "true");
       if (!this.isOpen) this.open();
       this.control.focus();
+      this.emitter.emit("invalid", this.nativeSelect?.validationMessage ?? "");
     };
     this.onNativeChange = () => {
       if (!this.nativeSelect || this.destroyed || this.syncingNative) return;
@@ -312,11 +417,17 @@ var ForgeSelect = class {
       templateResult: options.templateResult,
       templateSelection: options.templateSelection,
       filterOption: options.filterOption,
+      searchFields: options.searchFields ?? ["label", "description"],
+      tokenSearch: options.tokenSearch ?? true,
+      accentInsensitive: options.accentInsensitive ?? true,
+      searchScorer: options.searchScorer,
+      highlightSearch: options.highlightSearch ?? false,
       minSearchLength: Math.max(0, Math.floor(options.minSearchLength ?? 0)),
       minResultsForSearch: Math.max(0, Math.floor(options.minResultsForSearch ?? 0)),
       isOptionDisabled: options.isOptionDisabled,
       virtualScroll: options.virtualScroll,
-      itemHeight: options.itemHeight ?? DEFAULT_ITEM_HEIGHT,
+      itemHeight: typeof options.itemHeight === "number" ? Math.max(1, options.itemHeight) : DEFAULT_ITEM_HEIGHT,
+      variableItemHeight: options.itemHeight === "auto",
       language: options.language ?? "en",
       plugins: options.plugins ?? [],
       openOnFocus: options.openOnFocus ?? false,
@@ -340,6 +451,7 @@ var ForgeSelect = class {
     nativeSelect?.addEventListener("invalid", this.onNativeInvalid);
     this.nativeForm?.addEventListener("reset", this.onFormReset);
     for (const plugin of this.plugins) plugin.onInit?.(this);
+    for (const query of this.opts.ajax?.prefetch ?? []) void this.prefetchRemote(query);
   }
   applyNativeValues(values) {
     this.selected = [];
@@ -356,7 +468,7 @@ var ForgeSelect = class {
     this.root.classList.add("forge-select--open");
     this.control.setAttribute("aria-expanded", "true");
     document.addEventListener("mousedown", this.onDocumentMouseDown);
-    if (this.opts.ajax && !this.remoteLoaded) {
+    if (this.opts.ajax && (this.opts.ajax.loadOnOpen ?? true) && !this.remoteLoaded) {
       this.scheduleRemoteLoad(this.query, 0);
     }
     this.renderList();
@@ -377,6 +489,19 @@ var ForgeSelect = class {
     document.removeEventListener("mousedown", this.onDocumentMouseDown);
     window.removeEventListener("resize", this.onWindowResize);
     document.removeEventListener("scroll", this.onAncestorScroll, true);
+    if (this.ancestorScrollRafId != null) {
+      cancelAnimationFrame(this.ancestorScrollRafId);
+      this.ancestorScrollRafId = null;
+    }
+    if (this.scrollRafId != null) {
+      cancelAnimationFrame(this.scrollRafId);
+      this.scrollRafId = null;
+    }
+    if (this.typeaheadTimer) {
+      clearTimeout(this.typeaheadTimer);
+      this.typeaheadTimer = null;
+    }
+    this.typeaheadBuffer = "";
     this.highlightedIndex = -1;
     if (this.searchInput) {
       this.searchInput.value = "";
@@ -409,10 +534,14 @@ var ForgeSelect = class {
     this.destroyed = true;
     if (this.ajaxTimer) clearTimeout(this.ajaxTimer);
     this.ajaxController?.abort();
+    if (this.scrollRafId != null) cancelAnimationFrame(this.scrollRafId);
+    if (this.typeaheadTimer) clearTimeout(this.typeaheadTimer);
     this.nativeSelect?.removeEventListener("change", this.onNativeChange);
     this.nativeSelect?.removeEventListener("invalid", this.onNativeInvalid);
     this.nativeForm?.removeEventListener("reset", this.onFormReset);
     this.rowContentCache.clear();
+    this.rowHeightCache.clear();
+    this.searchIndex.clear();
     this.portalHost?.remove();
     this.root.remove();
     this.el.style.display = this.originalDisplay;
@@ -423,6 +552,107 @@ var ForgeSelect = class {
     if (this.opts.multiple) return [...this.selected];
     return this.selected[0] ?? null;
   }
+  getSearchQuery() {
+    return this.query;
+  }
+  setSearchQuery(query, options = {}) {
+    this.applySearchQuery(query, options.emitSearch ?? true);
+  }
+  isDropdownOpen() {
+    return this.isOpen;
+  }
+  updateOptions(options) {
+    if (options.data) this.setData(options.data);
+    if ("ajax" in options && options.ajax !== this.opts.ajax) {
+      this.opts.ajax = options.ajax;
+      this.remoteLoaded = false;
+      this.clearRemoteCache();
+    }
+    if (options.placeholder !== void 0) this.opts.placeholder = options.placeholder;
+    if (options.clearable !== void 0) this.opts.clearable = options.clearable;
+    if (options.allowCreate !== void 0) this.opts.allowCreate = options.allowCreate;
+    if (options.sortable !== void 0) this.opts.sortable = options.sortable;
+    if (options.closeOnSelect !== void 0) this.opts.closeOnSelect = options.closeOnSelect;
+    if ("maxSelections" in options)
+      this.opts.maxSelections = options.maxSelections == null || !Number.isFinite(options.maxSelections) ? void 0 : Math.max(0, Math.floor(options.maxSelections));
+    if (options.theme !== void 0) {
+      this.opts.theme = options.theme;
+      this.root.dataset.theme = options.theme;
+      if (this.portalHost) this.portalHost.dataset.theme = options.theme;
+    }
+    if (options.required !== void 0) {
+      this.opts.required = options.required;
+      if (options.required) this.control.setAttribute("aria-required", "true");
+      else this.control.removeAttribute("aria-required");
+      if (this.nativeSelect) this.nativeSelect.required = options.required;
+    }
+    if (options.templateResult !== void 0) this.opts.templateResult = options.templateResult;
+    if (options.templateSelection !== void 0) this.opts.templateSelection = options.templateSelection;
+    if (options.filterOption !== void 0) this.opts.filterOption = options.filterOption;
+    if (options.searchFields !== void 0) this.opts.searchFields = options.searchFields;
+    if (options.tokenSearch !== void 0) this.opts.tokenSearch = options.tokenSearch;
+    if (options.accentInsensitive !== void 0) this.opts.accentInsensitive = options.accentInsensitive;
+    if (options.searchScorer !== void 0) this.opts.searchScorer = options.searchScorer;
+    if (options.highlightSearch !== void 0) this.opts.highlightSearch = options.highlightSearch;
+    if (options.minSearchLength !== void 0)
+      this.opts.minSearchLength = Math.max(0, Math.floor(options.minSearchLength));
+    if (options.minResultsForSearch !== void 0)
+      this.opts.minResultsForSearch = Math.max(0, Math.floor(options.minResultsForSearch));
+    if (options.isOptionDisabled !== void 0) this.opts.isOptionDisabled = options.isOptionDisabled;
+    if (options.virtualScroll !== void 0) this.opts.virtualScroll = options.virtualScroll;
+    if (options.itemHeight !== void 0) {
+      this.opts.variableItemHeight = options.itemHeight === "auto";
+      if (typeof options.itemHeight === "number") this.opts.itemHeight = Math.max(1, options.itemHeight);
+      this.root.style.setProperty("--fs-item-height", `${this.opts.itemHeight}px`);
+      this.portalHost?.style.setProperty("--fs-item-height", `${this.opts.itemHeight}px`);
+    }
+    if (options.language !== void 0) {
+      this.opts.language = options.language;
+      this.strings = getStrings(options.language);
+      this.clearBtn.setAttribute("aria-label", this.strings.clearSelection);
+      this.searchInput?.setAttribute("aria-label", this.strings.search);
+    }
+    if (options.openOnFocus !== void 0) this.opts.openOnFocus = options.openOnFocus;
+    if (options.disabled !== void 0) {
+      if (options.disabled) this.disable();
+      else this.enable();
+    }
+    this.root.classList.toggle("forge-select--sortable", this.opts.sortable && this.opts.multiple);
+    this.updateSearchVisibility();
+    this.rowContentCache.clear();
+    this.rowHeightCache.clear();
+    this.searchIndex.clear();
+    this.renderValue();
+    if (this.isOpen) this.renderList();
+  }
+  validate() {
+    const valid = (!this.opts.required || this.selected.length > 0) && (this.control.dataset.validationMessage ?? "") === "";
+    this.control.classList.toggle("forge-select__control--invalid", !valid);
+    this.control.setAttribute("aria-invalid", String(!valid));
+    return valid;
+  }
+  setCustomValidity(message) {
+    this.nativeSelect?.setCustomValidity(message);
+    this.control.dataset.validationMessage = message;
+  }
+  reportValidity() {
+    const valid = this.validate() && (this.nativeSelect?.checkValidity() ?? true);
+    if (!valid) {
+      const message = this.nativeSelect?.validationMessage ?? this.control.dataset.validationMessage ?? "";
+      if (this.nativeSelect) return this.nativeSelect.reportValidity();
+      this.emitter.emit("invalid", message);
+    }
+    return valid;
+  }
+  reload() {
+    if (!this.opts.ajax) return;
+    this.clearRemoteCache();
+    this.remoteLoaded = false;
+    this.scheduleRemoteLoad(this.query, 0);
+  }
+  clearRemoteCache() {
+    this.remoteCache.clear();
+  }
   setValue(value, options = {}) {
     const values = value == null ? [] : Array.isArray(value) ? value : [value];
     const next = this.opts.multiple ? values : values.slice(0, 1);
@@ -445,7 +675,7 @@ var ForgeSelect = class {
     this.ajaxController?.abort();
     this.ajaxController = null;
     this.ajaxRequestId += 1;
-    this.loading = false;
+    this.setLoading(false);
     this.loadingMore = false;
     this.loadError = null;
     this.remoteLoaded = true;
@@ -455,6 +685,8 @@ var ForgeSelect = class {
     this.opts.data = data;
     this.updateSearchVisibility();
     this.rowContentCache.clear();
+    this.rowHeightCache.clear();
+    this.searchIndex.clear();
     this.highlightedIndex = -1;
     if (this.isOpen) this.renderList();
   }
@@ -628,25 +860,7 @@ var ForgeSelect = class {
     });
     if (this.searchInput) {
       this.searchInput.addEventListener("input", () => {
-        this.query = this.searchInput.value;
-        this.highlightedIndex = -1;
-        this.list.scrollTop = 0;
-        this.emitter.emit("search", this.query);
-        const trimmed = this.query.trim();
-        const belowMinLength = trimmed !== "" && trimmed.length < this.opts.minSearchLength;
-        if (this.opts.ajax && !belowMinLength) {
-          this.scheduleRemoteLoad(this.query, this.opts.ajax.debounce ?? 250);
-        } else {
-          if (belowMinLength) {
-            if (this.ajaxTimer) {
-              clearTimeout(this.ajaxTimer);
-              this.ajaxTimer = null;
-            }
-            this.ajaxController?.abort();
-            this.loading = false;
-          }
-          this.renderList();
-        }
+        this.applySearchQuery(this.searchInput.value, true);
       });
       this.searchInput.addEventListener("keydown", (event) => this.handleKeydown(event));
       this.searchInput.addEventListener("paste", (event) => {
@@ -693,10 +907,36 @@ var ForgeSelect = class {
       this.activateNavItem(navIndex);
     });
     this.list.addEventListener("scroll", () => {
-      if (this.usesVirtualScroll()) this.renderRows();
-      this.maybeLoadNextPage();
+      if (this.scrollRafId != null) return;
+      this.scrollRafId = requestAnimationFrame(() => {
+        this.scrollRafId = null;
+        if (this.usesVirtualScroll()) this.renderRows();
+        this.maybeLoadNextPage();
+      });
     });
   }
+  applySearchQuery(query, emitSearch) {
+    this.query = query;
+    if (this.searchInput && this.searchInput.value !== query) this.searchInput.value = query;
+    this.highlightedIndex = -1;
+    this.list.scrollTop = 0;
+    if (emitSearch) this.emitter.emit("search", query);
+    const trimmed = query.trim();
+    const belowMinLength = trimmed !== "" && trimmed.length < this.opts.minSearchLength;
+    if (this.opts.ajax && !belowMinLength) {
+      this.scheduleRemoteLoad(query, this.opts.ajax.debounce ?? 250);
+      return;
+    }
+    if (belowMinLength) {
+      if (this.ajaxTimer) {
+        clearTimeout(this.ajaxTimer);
+        this.ajaxTimer = null;
+      }
+      this.ajaxController?.abort();
+      this.setLoading(false);
+    }
+    this.renderList();
+  }
   handleKeydown(event) {
     if (this.isDisabled) return;
     switch (event.key) {
@@ -733,9 +973,63 @@ var ForgeSelect = class {
       case "ArrowLeft":
         if (this.isOpen && this.navigateTree("left")) event.preventDefault();
         break;
+      case "Home":
+        if (this.isOpen) {
+          event.preventDefault();
+          this.focusNavIndex(0);
+        }
+        break;
+      case "End":
+        if (this.isOpen) {
+          event.preventDefault();
+          this.focusNavIndex(this.navItems.length - 1);
+        }
+        break;
+      case "PageDown":
+        if (this.isOpen) {
+          event.preventDefault();
+          this.focusNavIndex(
+            Math.min(this.navItems.length - 1, (this.highlightedIndex === -1 ? 0 : this.highlightedIndex) + PAGE_SIZE)
+          );
+        }
+        break;
+      case "PageUp":
+        if (this.isOpen) {
+          event.preventDefault();
+          this.focusNavIndex(Math.max(0, (this.highlightedIndex === -1 ? 0 : this.highlightedIndex) - PAGE_SIZE));
+        }
+        break;
       case "Tab":
         this.close();
         break;
+      default:
+        if (this.isOpen && event.target === this.control && event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
+          this.handleTypeahead(event.key);
+        }
+        break;
+    }
+  }
+  /**
+   * Jumps the highlight to the next nav item (wrapping) whose label starts
+   * with the accumulated buffer, matching native <select> typeahead: rapid
+   * distinct keystrokes narrow the prefix, a pause resets it.
+   */
+  handleTypeahead(char) {
+    if (this.typeaheadTimer) clearTimeout(this.typeaheadTimer);
+    this.typeaheadBuffer += normalizeSearchText(char, this.opts.accentInsensitive);
+    this.typeaheadTimer = setTimeout(() => {
+      this.typeaheadBuffer = "";
+      this.typeaheadTimer = null;
+    }, TYPEAHEAD_RESET_MS);
+    const prefix = [...this.typeaheadBuffer].every((value) => value === this.typeaheadBuffer[0]) ? this.typeaheadBuffer[0] : this.typeaheadBuffer;
+    const count = this.navItems.length;
+    for (let step = 1; step <= count; step += 1) {
+      const index = (this.highlightedIndex + step + count) % count;
+      const item = this.navItems[index];
+      if (item.kind === "option" && normalizeSearchText(item.option.label, this.opts.accentInsensitive).startsWith(prefix)) {
+        this.focusNavIndex(index);
+        return;
+      }
     }
   }
   // ---------------------------------------------------------------- selection
@@ -826,7 +1120,10 @@ var ForgeSelect = class {
       this.control.classList.remove("forge-select__control--invalid");
       this.control.removeAttribute("aria-invalid");
     }
-    if (this.isOpen) this.renderList();
+    if (this.isOpen) {
+      if (this.opts.maxSelections != null) this.renderList();
+      else this.renderRows();
+    }
     if (emitChange) this.emitter.emit("change", this.getValue());
   }
   syncNativeSelect(dispatchChange = true) {
@@ -913,6 +1210,7 @@ var ForgeSelect = class {
     if (result.created) this.emitter.emit("create", result.option);
     this.emitter.emit("select", result.option);
     if (!this.opts.multiple || this.opts.closeOnSelect) this.close();
+    else if (this.isOpen) this.renderList();
   }
   activateNavItem(navIndex) {
     const item = this.navItems[navIndex];
@@ -1087,9 +1385,15 @@ var ForgeSelect = class {
   buildRows() {
     this.rows = [];
     this.navItems = [];
+    this.rowOffsetsCache = null;
     const trimmedQuery = this.query.trim();
-    const query = trimmedQuery.toLowerCase();
-    const matches = (option) => query === "" || (this.opts.filterOption ? this.opts.filterOption(option, trimmedQuery) : option.label.toLowerCase().includes(query) || (option.description?.toLowerCase().includes(query) ?? false));
+    const query = normalizeSearchText(trimmedQuery, this.opts.accentInsensitive);
+    const matches = (option) => query === "" || (this.opts.filterOption ? this.opts.filterOption(option, trimmedQuery) : this.searchIndex.score(option, trimmedQuery, {
+      fields: this.opts.searchFields,
+      tokenSearch: this.opts.tokenSearch,
+      accentInsensitive: this.opts.accentInsensitive,
+      scorer: this.opts.searchScorer
+    }) > 0);
     const subtreeMatches = (option) => query === "" || matches(option) || (option.children ?? []).some(subtreeMatches);
     const pushOption = (option, depth, parentValue) => {
       let navIndex = -1;
@@ -1145,6 +1449,27 @@ var ForgeSelect = class {
   usesVirtualScroll() {
     return this.opts.virtualScroll !== false && this.rows.length > VIRTUAL_THRESHOLD;
   }
+  rowKey(row, index) {
+    if (row.kind === "option") return `option:${row.option.value}`;
+    if (row.kind === "group") return `group:${row.label}:${index}`;
+    return `${row.kind}:${index}`;
+  }
+  measuredRowHeight(index) {
+    return this.opts.variableItemHeight ? this.rowHeightCache.get(this.rowKey(this.rows[index], index)) ?? this.opts.itemHeight : this.opts.itemHeight;
+  }
+  rowOffset(index) {
+    if (!this.opts.variableItemHeight) return index * this.opts.itemHeight;
+    let offset = 0;
+    for (let i = 0; i < index; i += 1) offset += this.measuredRowHeight(i);
+    return offset;
+  }
+  rowOffsets() {
+    if (this.rowOffsetsCache) return this.rowOffsetsCache;
+    const offsets = [0];
+    for (let i = 0; i < this.rows.length; i += 1) offsets.push(offsets[i] + this.measuredRowHeight(i));
+    this.rowOffsetsCache = offsets;
+    return offsets;
+  }
   renderList() {
     this.buildRows();
     this.renderRows();
@@ -1161,26 +1486,49 @@ var ForgeSelect = class {
     const virtual = this.usesVirtualScroll();
     this.list.textContent = "";
     const rowHeight = this.opts.itemHeight;
+    const offsets = this.opts.variableItemHeight ? this.rowOffsets() : null;
     let start = 0;
     let end = this.rows.length;
     if (virtual) {
       const viewport = clientHeight || rowHeight * 8;
-      start = Math.max(0, Math.floor(scrollTop / rowHeight) - VIRTUAL_BUFFER);
-      end = Math.min(this.rows.length, start + Math.ceil(viewport / rowHeight) + VIRTUAL_BUFFER * 2);
+      if (this.opts.variableItemHeight) {
+        while (start < this.rows.length && offsets[start + 1] < scrollTop) start += 1;
+        start = Math.max(0, start - VIRTUAL_BUFFER);
+        end = start;
+        const target = scrollTop + viewport + VIRTUAL_BUFFER * rowHeight;
+        while (end < this.rows.length && offsets[end] < target) end += 1;
+      } else {
+        start = Math.max(0, Math.floor(scrollTop / rowHeight) - VIRTUAL_BUFFER);
+        end = Math.min(this.rows.length, start + Math.ceil(viewport / rowHeight) + VIRTUAL_BUFFER * 2);
+      }
       const topSpacer = document.createElement("li");
       topSpacer.className = "forge-select__spacer";
       topSpacer.setAttribute("aria-hidden", "true");
-      topSpacer.style.height = `${start * rowHeight}px`;
+      topSpacer.style.height = `${offsets?.[start] ?? this.rowOffset(start)}px`;
       this.list.append(topSpacer);
     }
+    const appended = [];
     for (let i = start; i < end; i++) {
-      this.list.append(this.renderRow(this.rows[i]));
+      const element = this.renderRow(this.rows[i]);
+      this.list.append(element);
+      appended.push(element);
+    }
+    if (this.opts.variableItemHeight) {
+      for (let i = start; i < end; i++) {
+        const element = appended[i - start];
+        const measured = element.getBoundingClientRect().height || element.offsetHeight;
+        if (measured > 0) {
+          const key = this.rowKey(this.rows[i], i);
+          if (this.rowHeightCache.get(key) !== measured) this.rowOffsetsCache = null;
+          this.rowHeightCache.set(key, measured);
+        }
+      }
     }
     if (virtual) {
       const bottomSpacer = document.createElement("li");
       bottomSpacer.className = "forge-select__spacer";
       bottomSpacer.setAttribute("aria-hidden", "true");
-      bottomSpacer.style.height = `${(this.rows.length - end) * rowHeight}px`;
+      bottomSpacer.style.height = `${offsets ? offsets[this.rows.length] - offsets[end] : this.rowOffset(this.rows.length) - this.rowOffset(end)}px`;
       this.list.append(bottomSpacer);
       if (this.list.scrollTop !== scrollTop) {
         this.list.scrollTop = scrollTop;
@@ -1247,6 +1595,7 @@ var ForgeSelect = class {
         if (isSelected) li.classList.add("forge-select__option--selected");
         if (this.opts.multiple && row.hasChildren && computeCheckState(row.option, this.selected, this.isOptionDisabled) === "some") {
           li.classList.add("forge-select__option--indeterminate");
+          li.dataset.selectionState = "mixed";
         }
         if (row.depth > 0) {
           li.style.paddingLeft = `calc(12px + ${row.depth} * var(--fs-tree-indent, 18px))`;
@@ -1282,6 +1631,28 @@ var ForgeSelect = class {
    * cached content state-free.
    */
   optionContent(option) {
+    if (this.opts.highlightSearch && this.query.trim() && !this.opts.templateResult) {
+      const holder = document.createElement("span");
+      holder.className = "forge-select__option-content";
+      renderOptionContent(holder, option, void 0);
+      const label = holder.querySelector(".forge-select__option-label") ?? holder;
+      const ranges = findNormalizedRanges(option.label, this.query, this.opts.accentInsensitive);
+      if (ranges.length) {
+        label.textContent = "";
+        let cursor = 0;
+        for (const [start, end] of ranges) {
+          if (start < cursor) continue;
+          label.append(document.createTextNode(option.label.slice(cursor, start)));
+          const mark = document.createElement("mark");
+          mark.className = "forge-select__match";
+          mark.textContent = option.label.slice(start, end);
+          label.append(mark);
+          cursor = end;
+        }
+        label.append(document.createTextNode(option.label.slice(cursor)));
+      }
+      return holder;
+    }
     let cached = this.rowContentCache.get(option.value);
     if (!cached) {
       const holder = document.createElement("span");
@@ -1302,14 +1673,15 @@ var ForgeSelect = class {
     this.focusNavIndex(next);
   }
   focusNavIndex(next) {
+    if (this.navItems.length === 0) return;
     this.highlightedIndex = next;
     if (this.usesVirtualScroll()) {
       const rowIndex = this.rows.findIndex(
         (row) => (row.kind === "option" || row.kind === "create") && row.navIndex === next
       );
       if (rowIndex >= 0) {
-        const rowHeight = this.opts.itemHeight;
-        const top = rowIndex * rowHeight;
+        const rowHeight = this.measuredRowHeight(rowIndex);
+        const top = this.rowOffset(rowIndex);
         const viewport = this.list.clientHeight || rowHeight * 8;
         let target = this.list.scrollTop;
         if (top < target) target = top;
@@ -1374,7 +1746,7 @@ var ForgeSelect = class {
     this.ajaxController = null;
     this.page = 0;
     this.hasMore = true;
-    this.loading = true;
+    this.setLoading(true);
     this.loadingMore = false;
     this.loadError = null;
     this.renderList();
@@ -1383,6 +1755,55 @@ var ForgeSelect = class {
       void this.loadRemote(query, { requestId });
     }, delay);
   }
+  setLoading(loading) {
+    if (this.loading === loading) return;
+    this.loading = loading;
+    this.emitter.emit("loading", loading);
+  }
+  remoteCacheKey(query, page) {
+    return `${query}\0${page}`;
+  }
+  async requestRemote(query, page, signal) {
+    const ajax = this.opts.ajax;
+    const attempts = Math.max(0, Math.floor(ajax.retry ?? 0)) + 1;
+    let lastError;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      try {
+        if (ajax.request) return await ajax.request(query, page, signal);
+        const response = await fetch(buildUrl(ajax, query, page), { signal });
+        if (response.ok === false) throw new Error(`ForgeSelect: remote request failed with HTTP ${response.status}`);
+        return await response.json();
+      } catch (error) {
+        lastError = error;
+        if (signal.aborted || attempt === attempts - 1) throw error;
+        const delay = Math.max(0, ajax.retryDelay ?? 250) * 2 ** attempt;
+        await new Promise((resolve, reject) => {
+          const timer = setTimeout(resolve, delay);
+          signal.addEventListener(
+            "abort",
+            () => {
+              clearTimeout(timer);
+              reject(new DOMException("Aborted", "AbortError"));
+            },
+            { once: true }
+          );
+        });
+      }
+    }
+    throw lastError;
+  }
+  async prefetchRemote(query) {
+    const ajax = this.opts.ajax;
+    if (!ajax || (ajax.cacheTtl ?? 3e4) <= 0) return;
+    const key = this.remoteCacheKey(query, 0);
+    if (this.remoteCache.get(key)) return;
+    const controller = new AbortController();
+    try {
+      const json = await this.requestRemote(query, 0, controller.signal);
+      this.remoteCache.set(key, normalizeRemoteResult(ajax, json), ajax.cacheTtl ?? 3e4);
+    } catch {
+    }
+  }
   /**
    * Fires on every list scroll. Only acts when pagination is opted into via
    * `ajax.pagination`; reads real scroll geometry rather than row counts so
@@ -1407,23 +1828,22 @@ var ForgeSelect = class {
     this.ajaxController = controller;
     const page = append ? this.page + 1 : 0;
     try {
-      let json;
-      if (ajax.request) {
-        json = await ajax.request(query, page, controller.signal);
-      } else {
-        const url = buildUrl(ajax, query, page);
-        const response = await fetch(url, { signal: controller.signal });
-        if (response.ok === false) throw new Error(`ForgeSelect: remote request failed with HTTP ${response.status}`);
-        json = await response.json();
+      const key = this.remoteCacheKey(query, page);
+      let result = this.remoteCache.get(key);
+      if (!result) {
+        const json = await this.requestRemote(query, page, controller.signal);
+        result = normalizeRemoteResult(ajax, json);
+        this.remoteCache.set(key, result, ajax.cacheTtl ?? 3e4);
       }
       if (activeRequestId !== this.ajaxRequestId || this.destroyed) return;
-      const { options, hasMore } = normalizeRemoteResult(ajax, json);
+      const { options, hasMore } = result;
       if (append) {
         const existing = collectValues(this.data);
         this.data = [...this.data, ...options.filter((o) => !existing.has(o.value))];
       } else {
         this.data = options;
         this.rowContentCache.clear();
+        this.rowHeightCache.clear();
       }
       this.page = page;
       this.hasMore = hasMore;
@@ -1435,6 +1855,7 @@ var ForgeSelect = class {
       if (!append) {
         this.data = [];
         this.rowContentCache.clear();
+        this.rowHeightCache.clear();
       }
       this.hasMore = false;
       this.loadError = error;
@@ -1442,7 +1863,7 @@ var ForgeSelect = class {
     } finally {
       if (activeRequestId === this.ajaxRequestId && !this.destroyed) {
         this.ajaxController = null;
-        this.loading = false;
+        this.setLoading(false);
         this.loadingMore = false;
         if (this.isOpen) this.renderList();
       }