forge-select 0.3.0 → 0.5.0

package/dist/index.js

@@ -24,6 +24,17 @@ var Emitter = class {
   }
 };
 
+// src/dropdown-position.ts
+function computeDropdownPlacement(controlRect, dropdownHeight, viewportHeight, gap = 4) {
+  const spaceBelow = viewportHeight - controlRect.bottom;
+  const spaceAbove = controlRect.top;
+  const dropUp = dropdownHeight > spaceBelow && spaceAbove > spaceBelow;
+  return {
+    dropUp,
+    top: dropUp ? controlRect.top - dropdownHeight - gap : controlRect.bottom + gap
+  };
+}
+
 // src/i18n.ts
 var locales = {
   en: {
@@ -35,7 +46,9 @@ var locales = {
     clearSelection: "Clear selection",
     removeItem: "Remove {label}",
     search: "Search",
-    reorderHint: "{label}. Press Alt+Left or Alt+Right to reorder."
+    reorderHint: "{label}. Press Alt+Left or Alt+Right to reorder.",
+    minSearchLength: "Type {count} or more characters to search",
+    maximumSelected: "Maximum of {count} selections reached"
   },
   vi: {
     noResults: "Kh\xF4ng t\xECm th\u1EA5y k\u1EBFt qu\u1EA3",
@@ -46,7 +59,9 @@ var locales = {
     clearSelection: "X\xF3a l\u1EF1a ch\u1ECDn",
     removeItem: "X\xF3a {label}",
     search: "T\xECm ki\u1EBFm",
-    reorderHint: "{label}. Nh\u1EA5n Alt+Tr\xE1i ho\u1EB7c Alt+Ph\u1EA3i \u0111\u1EC3 s\u1EAFp x\u1EBFp l\u1EA1i."
+    reorderHint: "{label}. Nh\u1EA5n Alt+Tr\xE1i ho\u1EB7c Alt+Ph\u1EA3i \u0111\u1EC3 s\u1EAFp x\u1EBFp l\u1EA1i.",
+    minSearchLength: "Nh\u1EADp th\xEAm {count} k\xFD t\u1EF1 \u0111\u1EC3 t\xECm ki\u1EBFm",
+    maximumSelected: "\u0110\xE3 \u0111\u1EA1t t\u1ED1i \u0111a {count} l\u1EF1a ch\u1ECDn"
   }
 };
 function getStrings(language) {
@@ -122,6 +137,7 @@ function renderOptionContent(container, option, template, variant = "row") {
 
 // src/remote.ts
 function buildUrl(ajax, query, page) {
+  if (!ajax.url) throw new Error("ForgeSelect: ajax requires either url or request.");
   if (typeof ajax.url === "function") return ajax.url(query, page);
   if (!ajax.params) return ajax.url;
   const params = new URLSearchParams();
@@ -140,22 +156,106 @@ function normalizeRemoteResult(ajax, response) {
   return { options: result.options, hasMore: ajax.pagination ? Boolean(result.hasMore) : false };
 }
 
+// src/remote-cache.ts
+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) 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;
 }
-function collectDescendantValues(option) {
+var defaultIsDisabled = (option) => !!option.disabled;
+function collectDescendantValues(option, isDisabled = defaultIsDisabled) {
   if (!option.children) return [];
   const values = [];
   for (const child of option.children) {
-    if (!child.disabled) values.push(child.value);
-    values.push(...collectDescendantValues(child));
+    if (!isDisabled(child)) values.push(child.value);
+    values.push(...collectDescendantValues(child, isDisabled));
   }
   return values;
 }
-function computeCheckState(option, selected) {
+function computeCheckState(option, selected, isDisabled = defaultIsDisabled) {
   if (!option.children?.length) return selected.includes(option.value) ? "all" : "none";
-  const states = option.children.filter((child) => !child.disabled).map((child) => computeCheckState(child, selected));
+  const states = option.children.filter((child) => !isDisabled(child)).map((child) => computeCheckState(child, selected, isDisabled));
   if (states.length === 0) return "none";
   if (states.every((state) => state === "all")) return "all";
   if (states.every((state) => state === "none")) return "none";
@@ -176,11 +276,11 @@ function findOption(items, value) {
   }
   return void 0;
 }
-function syncTreeAncestors(items, selected) {
+function syncTreeAncestors(items, selected, isDisabled = defaultIsDisabled) {
   const sync = (option) => {
     if (!option.children?.length) return;
     for (const child of option.children) sync(child);
-    const state = computeCheckState(option, selected);
+    const state = computeCheckState(option, selected, isDisabled);
     const index = selected.indexOf(option.value);
     if (state === "all" && index === -1) selected.push(option.value);
     else if (state !== "all" && index !== -1) selected.splice(index, 1);
@@ -214,6 +314,7 @@ var ForgeSelect = class {
     this.emitter = new Emitter();
     this.uid = `forge-select-${++uidCounter}`;
     this.searchInput = null;
+    this.portalHost = null;
     this.isOpen = false;
     this.isDisabled = false;
     this.destroyed = false;
@@ -222,6 +323,8 @@ var ForgeSelect = class {
     this.navItems = [];
     this.highlightedIndex = -1;
     this.rowContentCache = /* @__PURE__ */ new Map();
+    this.rowHeightCache = /* @__PURE__ */ new Map();
+    this.searchIndex = new SearchIndex();
     this.expandedValues = /* @__PURE__ */ new Set();
     this.loading = false;
     this.loadingMore = false;
@@ -231,14 +334,33 @@ var ForgeSelect = class {
     this.ajaxRequestId = 0;
     this.ajaxController = null;
     this.remoteLoaded = false;
+    this.remoteCache = new RemoteCache();
     this.loadError = null;
     this.originalDisplay = "";
     this.originalDisabled = false;
     this.nativeSelect = null;
     this.nativeForm = null;
     this.syncingNative = false;
+    /** Combines the static `disabled` field with the dynamic `isOptionDisabled` callback. */
+    this.isOptionDisabled = (option) => option.disabled === true || (this.opts.isOptionDisabled?.(option) ?? false);
+    this.pointerDownOnControl = false;
     this.onDocumentMouseDown = (event) => {
-      if (!this.root.contains(event.target)) this.close();
+      const target = event.target;
+      if (!this.root.contains(target) && !this.portalHost?.contains(target)) this.close();
+    };
+    this.onWindowResize = () => {
+      this.positionDropdown();
+    };
+    this.onAncestorScroll = () => {
+      if (this.portalHost) this.positionDropdown();
+    };
+    this.onNativeInvalid = (event) => {
+      event.preventDefault();
+      this.control.classList.add("forge-select__control--invalid");
+      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;
@@ -267,19 +389,35 @@ var ForgeSelect = class {
       clearable: options.clearable ?? false,
       allowCreate: options.allowCreate ?? false,
       sortable: options.sortable ?? false,
+      closeOnSelect: options.closeOnSelect ?? false,
+      maxSelections: options.maxSelections == null || !Number.isFinite(options.maxSelections) ? void 0 : Math.max(0, Math.floor(options.maxSelections)),
       theme: options.theme ?? "default",
       disabled: options.disabled ?? nativeSelect?.disabled ?? false,
+      required: options.required ?? nativeSelect?.required ?? false,
       data: options.data,
       ajax: options.ajax,
       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 ?? []
+      plugins: options.plugins ?? [],
+      openOnFocus: options.openOnFocus ?? false,
+      dropdownParent: options.dropdownParent
     };
     this.strings = getStrings(this.opts.language);
     this.plugins = this.opts.plugins;
+    if (nativeSelect) nativeSelect.required = this.opts.required;
     this.data = this.opts.data ?? (nativeSelect ? parseNativeOptions(nativeSelect) : []);
     if (nativeSelect && !this.opts.data) {
       const nativeOptions = Array.from(nativeSelect.options);
@@ -292,8 +430,10 @@ var ForgeSelect = class {
     this.renderValue();
     if (this.opts.disabled) this.disable();
     nativeSelect?.addEventListener("change", this.onNativeChange);
+    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 = [];
@@ -310,11 +450,14 @@ 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();
-    if (this.searchInput) this.searchInput.focus();
+    this.positionDropdown();
+    window.addEventListener("resize", this.onWindowResize);
+    document.addEventListener("scroll", this.onAncestorScroll, true);
+    if (this.searchInput && !this.searchInput.hidden) this.searchInput.focus();
     this.emitter.emit("open");
     for (const plugin of this.plugins) plugin.onOpen?.(this);
   }
@@ -323,8 +466,11 @@ var ForgeSelect = class {
     this.isOpen = false;
     this.dropdown.hidden = true;
     this.root.classList.remove("forge-select--open");
+    this.root.classList.remove("forge-select--drop-up");
     this.control.setAttribute("aria-expanded", "false");
     document.removeEventListener("mousedown", this.onDocumentMouseDown);
+    window.removeEventListener("resize", this.onWindowResize);
+    document.removeEventListener("scroll", this.onAncestorScroll, true);
     this.highlightedIndex = -1;
     if (this.searchInput) {
       this.searchInput.value = "";
@@ -333,6 +479,23 @@ var ForgeSelect = class {
     this.emitter.emit("close");
     for (const plugin of this.plugins) plugin.onClose?.(this);
   }
+  /**
+   * Flips the dropdown above the control when there isn't enough room below
+   * but there is above. Recomputed on open() and on window resize — the
+   * dropdown is positioned absolutely inside the relatively-positioned root,
+   * so it already tracks the control correctly on page scroll without
+   * needing a scroll listener.
+   */
+  positionDropdown() {
+    const controlRect = this.control.getBoundingClientRect();
+    const placement = computeDropdownPlacement(controlRect, this.dropdown.offsetHeight, window.innerHeight);
+    this.root.classList.toggle("forge-select--drop-up", placement.dropUp);
+    if (this.portalHost) {
+      this.portalHost.style.top = `${placement.top}px`;
+      this.portalHost.style.left = `${controlRect.left}px`;
+      this.portalHost.style.width = `${controlRect.width}px`;
+    }
+  }
   destroy() {
     if (this.destroyed) return;
     this.close();
@@ -341,8 +504,12 @@ var ForgeSelect = class {
     if (this.ajaxTimer) clearTimeout(this.ajaxTimer);
     this.ajaxController?.abort();
     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;
     if (this.nativeSelect) this.nativeSelect.disabled = this.originalDisabled;
@@ -352,6 +519,106 @@ 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.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);
@@ -360,6 +627,53 @@ var ForgeSelect = class {
     for (const v of next) this.selectValue(v, false);
     this.afterSelectionChange(options.emitChange ?? true);
   }
+  /**
+   * Replaces the option list after construction. An open dropdown re-renders
+   * immediately; a selection whose value isn't in the new data stays
+   * selected (rendered via the already-selected option's own label/avatar,
+   * the same fallback used for values selected from a stale ajax page).
+   */
+  setData(data) {
+    if (this.ajaxTimer) {
+      clearTimeout(this.ajaxTimer);
+      this.ajaxTimer = null;
+    }
+    this.ajaxController?.abort();
+    this.ajaxController = null;
+    this.ajaxRequestId += 1;
+    this.setLoading(false);
+    this.loadingMore = false;
+    this.loadError = null;
+    this.remoteLoaded = true;
+    this.page = 0;
+    this.hasMore = false;
+    this.data = data;
+    this.opts.data = data;
+    this.updateSearchVisibility();
+    this.rowContentCache.clear();
+    this.searchIndex.clear();
+    this.highlightedIndex = -1;
+    if (this.isOpen) this.renderList();
+  }
+  /**
+   * Multi-select only: selects every currently non-disabled option, including
+   * nested tree descendants and options inside groups. If `maxSelections` is
+   * set, stops once the cap is reached rather than exceeding it. A no-op for
+   * single-select.
+   */
+  selectAll() {
+    if (!this.opts.multiple) return;
+    this.selected = [];
+    for (const value of this.allSelectableValues()) {
+      const option = this.findOption(value);
+      if (option && this.canSelectOption(option)) this.selectValue(value, false);
+    }
+    this.afterSelectionChange();
+  }
+  /** Clears every selection. Equivalent to `setValue(null)`. */
+  clearAll() {
+    this.clearSelection();
+  }
   enable() {
     this.isDisabled = false;
     this.root.classList.remove("forge-select--disabled");
@@ -405,7 +719,22 @@ var ForgeSelect = class {
       }
     }
   }
+  shouldShowSearch() {
+    return this.opts.searchable && (this.opts.ajax != null || collectValues(this.data).size >= this.opts.minResultsForSearch);
+  }
+  updateSearchVisibility() {
+    if (!this.searchInput) return;
+    this.searchInput.hidden = !this.shouldShowSearch();
+    if (this.searchInput.hidden) {
+      this.searchInput.value = "";
+      this.query = "";
+    }
+  }
   buildDom() {
+    const portalParent = typeof this.opts.dropdownParent === "string" ? document.querySelector(this.opts.dropdownParent) : this.opts.dropdownParent;
+    if (this.opts.dropdownParent && !portalParent) {
+      throw new Error(`ForgeSelect: dropdown parent not found: ${String(this.opts.dropdownParent)}`);
+    }
     this.root = document.createElement("div");
     this.root.className = "forge-select";
     this.root.dataset.theme = this.opts.theme;
@@ -417,6 +746,7 @@ var ForgeSelect = class {
     this.control.setAttribute("aria-haspopup", "listbox");
     this.control.setAttribute("aria-expanded", "false");
     this.control.setAttribute("aria-controls", `${this.uid}-list`);
+    if (this.opts.required) this.control.setAttribute("aria-required", "true");
     this.control.tabIndex = 0;
     this.applyAccessibleName();
     this.valueEl = document.createElement("div");
@@ -441,6 +771,7 @@ var ForgeSelect = class {
       this.searchInput.setAttribute("aria-label", this.strings.search);
       this.searchInput.setAttribute("aria-autocomplete", "list");
       this.searchInput.setAttribute("aria-controls", `${this.uid}-list`);
+      this.searchInput.hidden = !this.shouldShowSearch();
       this.dropdown.append(this.searchInput);
     }
     this.list = document.createElement("ul");
@@ -453,9 +784,18 @@ var ForgeSelect = class {
     this.liveRegion.className = "forge-select__sr-only";
     this.liveRegion.setAttribute("role", "status");
     this.liveRegion.setAttribute("aria-live", "polite");
-    this.root.append(this.control, this.dropdown, this.liveRegion);
+    this.root.append(this.control, this.liveRegion);
+    if (!portalParent) this.root.append(this.dropdown);
     this.el.style.display = "none";
     this.el.insertAdjacentElement("afterend", this.root);
+    if (portalParent) {
+      this.portalHost = document.createElement("div");
+      this.portalHost.className = "forge-select forge-select--portal-host";
+      this.portalHost.dataset.theme = this.opts.theme;
+      this.portalHost.style.setProperty("--fs-item-height", `${this.opts.itemHeight}px`);
+      this.portalHost.append(this.dropdown);
+      portalParent.append(this.portalHost);
+    }
     this.bindEvents();
   }
   bindEvents() {
@@ -470,23 +810,46 @@ var ForgeSelect = class {
       else this.open();
     });
     this.control.addEventListener("keydown", (event) => this.handleKeydown(event));
+    this.control.addEventListener("mousedown", () => {
+      this.pointerDownOnControl = true;
+    });
+    this.control.addEventListener("focus", () => {
+      if (this.opts.openOnFocus && !this.pointerDownOnControl && !this.isOpen && !this.isDisabled) {
+        this.open();
+      }
+      this.pointerDownOnControl = false;
+    });
     this.clearBtn.addEventListener("click", (event) => {
       event.stopPropagation();
       this.clearSelection();
     });
     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);
-        if (this.opts.ajax) {
-          this.scheduleRemoteLoad(this.query, this.opts.ajax.debounce ?? 250);
-        } else {
-          this.renderList();
-        }
+        this.applySearchQuery(this.searchInput.value, true);
       });
       this.searchInput.addEventListener("keydown", (event) => this.handleKeydown(event));
+      this.searchInput.addEventListener("paste", (event) => {
+        if (!this.opts.multiple || !this.opts.allowCreate) return;
+        const text = event.clipboardData?.getData("text") ?? "";
+        const labels = text.split(/[,\n]+/).map((s) => s.trim()).filter(Boolean);
+        if (labels.length < 2) return;
+        event.preventDefault();
+        const created = [];
+        for (const label of labels) {
+          const result = this.createTag(label);
+          if (result) created.push(result);
+        }
+        if (created.length === 0) return;
+        this.searchInput.value = "";
+        this.query = "";
+        this.afterSelectionChange();
+        for (const result of created) {
+          if (result.created) this.emitter.emit("create", result.option);
+          this.emitter.emit("select", result.option);
+        }
+        if (this.opts.closeOnSelect) this.close();
+        else this.renderList();
+      });
     }
     this.list.addEventListener("click", (event) => {
       const target = event.target;
@@ -499,7 +862,12 @@ var ForgeSelect = class {
         return;
       }
       const li = target.closest("li[data-nav-index]");
-      if (!li) return;
+      if (!li) {
+        const optionRow = target.closest("li[data-option-value]");
+        const option = optionRow ? this.findOption(optionRow.dataset.optionValue) : void 0;
+        if (option && this.hasReachedMaximum() && !this.selected.includes(option.value)) this.announceMaximum(option);
+        return;
+      }
       const navIndex = Number(li.dataset.navIndex);
       this.activateNavItem(navIndex);
     });
@@ -508,6 +876,29 @@ var ForgeSelect = class {
       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;
+    this.rowContentCache.clear();
+    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) {
@@ -550,36 +941,61 @@ var ForgeSelect = class {
     }
   }
   // ---------------------------------------------------------------- selection
+  canSelectOption(option) {
+    if (this.opts.maxSelections == null) return true;
+    const projected = [...this.selected];
+    if (!projected.includes(option.value)) projected.push(option.value);
+    for (const value of collectDescendantValues(option, this.isOptionDisabled)) {
+      if (!projected.includes(value)) projected.push(value);
+    }
+    syncTreeAncestors(this.data, projected, this.isOptionDisabled);
+    return projected.length <= this.opts.maxSelections;
+  }
+  hasReachedMaximum() {
+    return this.opts.maxSelections != null && this.selected.length >= this.opts.maxSelections;
+  }
+  announceMaximum(option) {
+    const limit = this.opts.maxSelections;
+    if (limit == null) return;
+    this.liveRegion.textContent = format(this.strings.maximumSelected, { count: String(limit) });
+    this.emitter.emit("maximum", { limit, option });
+  }
   selectValue(value, notify) {
     if (this.selected.includes(value)) return;
     const option = this.findOption(value) ?? this.selectedOptions.get(value) ?? { value, label: value };
     this.selectedOptions.set(value, option);
     if (this.opts.multiple) {
       this.selected.push(value);
-      for (const v of collectDescendantValues(option)) {
+      for (const v of collectDescendantValues(option, this.isOptionDisabled)) {
         if (!this.selected.includes(v)) this.selected.push(v);
       }
       this.syncTreeAncestors();
     } else {
       this.selected = [value];
     }
-    if (notify) this.afterSelectionChange();
+    if (notify) {
+      this.afterSelectionChange();
+      this.emitter.emit("select", option);
+    }
   }
   deselectValue(value, notify) {
     const index = this.selected.indexOf(value);
     if (index === -1) return;
+    const option = this.findOption(value) ?? this.selectedOptions.get(value);
     this.selected.splice(index, 1);
     if (this.opts.multiple) {
-      const option = this.findOption(value) ?? this.selectedOptions.get(value);
       if (option) {
-        for (const v of collectDescendantValues(option)) {
+        for (const v of collectDescendantValues(option, this.isOptionDisabled)) {
           const i = this.selected.indexOf(v);
           if (i !== -1) this.selected.splice(i, 1);
         }
       }
       this.syncTreeAncestors();
     }
-    if (notify) this.afterSelectionChange();
+    if (notify) {
+      this.afterSelectionChange();
+      this.emitter.emit("unselect", option ?? { value, label: value });
+    }
   }
   /**
    * Keeps every tree parent's own membership in `selected` consistent with
@@ -588,7 +1004,7 @@ var ForgeSelect = class {
    * No-op for data with no `children` anywhere.
    */
   syncTreeAncestors() {
-    syncTreeAncestors(this.data, this.selected);
+    syncTreeAncestors(this.data, this.selected, this.isOptionDisabled);
   }
   clearSelection() {
     if (this.selected.length === 0) return;
@@ -596,9 +1012,22 @@ var ForgeSelect = class {
     this.emitter.emit("clear");
     this.afterSelectionChange();
   }
+  allSelectableValues() {
+    const values = [];
+    const visit = (option) => {
+      if (!this.isOptionDisabled(option)) values.push(option.value);
+      option.children?.forEach(visit);
+    };
+    for (const item of this.data) (isGroup(item) ? item.options : [item]).forEach(visit);
+    return values;
+  }
   afterSelectionChange(emitChange = true) {
     this.renderValue();
     this.syncNativeSelect(emitChange);
+    if (!this.opts.required || this.selected.length > 0) {
+      this.control.classList.remove("forge-select__control--invalid");
+      this.control.removeAttribute("aria-invalid");
+    }
     if (this.isOpen) this.renderList();
     if (emitChange) this.emitter.emit("change", this.getValue());
   }
@@ -634,17 +1063,58 @@ var ForgeSelect = class {
   findOption(value) {
     return findOption(this.data, value);
   }
+  findOptionByLabel(label) {
+    const lower = label.toLowerCase();
+    const search = (options) => {
+      for (const option of options) {
+        if (option.label.toLowerCase() === lower) return option;
+        const found = option.children ? search(option.children) : void 0;
+        if (found) return found;
+      }
+      return void 0;
+    };
+    for (const item of this.data) {
+      const found = search(isGroup(item) ? item.options : [item]);
+      if (found) return found;
+    }
+    return void 0;
+  }
+  /** Selects an existing option matching `label` exactly, or creates and selects a new one. */
+  createTag(label) {
+    const trimmed = label.trim();
+    if (!trimmed) return void 0;
+    const existing = this.findOptionByLabel(trimmed);
+    if (existing) {
+      if (this.selected.includes(existing.value)) return void 0;
+      if (this.opts.multiple && !this.canSelectOption(existing)) {
+        this.announceMaximum(existing);
+        return void 0;
+      }
+      this.selectValue(existing.value, false);
+      return { option: existing, created: false };
+    }
+    const option = { value: trimmed, label: trimmed };
+    if (this.opts.multiple && !this.canSelectOption(option)) {
+      this.announceMaximum(option);
+      return void 0;
+    }
+    this.data.push(option);
+    this.selectValue(option.value, false);
+    return { option, created: true };
+  }
   createFromQuery() {
     const label = this.query.trim();
     if (!label) return;
-    const option = { value: label, label };
-    this.data.push(option);
+    const result = this.createTag(label);
+    if (!result) return;
     if (this.searchInput) {
       this.searchInput.value = "";
       this.query = "";
     }
-    this.selectValue(option.value, true);
-    if (!this.opts.multiple) this.close();
+    this.afterSelectionChange();
+    if (result.created) this.emitter.emit("create", result.option);
+    this.emitter.emit("select", result.option);
+    if (!this.opts.multiple || this.opts.closeOnSelect) this.close();
   }
   activateNavItem(navIndex) {
     const item = this.navItems[navIndex];
@@ -655,8 +1125,17 @@ var ForgeSelect = class {
     }
     const { value } = item.option;
     if (this.opts.multiple) {
-      if (this.selected.includes(value)) this.deselectValue(value, true);
-      else this.selectValue(value, true);
+      let changed = false;
+      if (this.selected.includes(value)) {
+        this.deselectValue(value, true);
+        changed = true;
+      } else if (this.canSelectOption(item.option)) {
+        this.selectValue(value, true);
+        changed = true;
+      } else {
+        this.announceMaximum(item.option);
+      }
+      if (changed && this.opts.closeOnSelect) this.close();
     } else {
       this.selectValue(value, true);
       this.close();
@@ -772,6 +1251,7 @@ var ForgeSelect = class {
       this.selected = order;
       this.suppressNextTagClick = true;
       this.afterSelectionChange();
+      this.emitter.emit("reorder", [...this.selected]);
     };
     tag.addEventListener("pointerdown", (event) => {
       if (this.isDisabled || event.button !== 0) return;
@@ -795,6 +1275,7 @@ var ForgeSelect = class {
     [next[index], next[targetIndex]] = [next[targetIndex], next[index]];
     this.selected = next;
     this.afterSelectionChange();
+    this.emitter.emit("reorder", [...this.selected]);
     this.focusTagByValue(value);
   }
   focusTagByValue(value) {
@@ -808,12 +1289,19 @@ var ForgeSelect = class {
   buildRows() {
     this.rows = [];
     this.navItems = [];
-    const query = this.query.trim().toLowerCase();
-    const matches = (option) => query === "" || option.label.toLowerCase().includes(query) || (option.description?.toLowerCase().includes(query) ?? false);
+    const trimmedQuery = this.query.trim();
+    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;
-      if (!option.disabled) {
+      const interactionDisabled = this.isOptionDisabled(option) || this.hasReachedMaximum() && !this.selected.includes(option.value);
+      if (!interactionDisabled) {
         navIndex = this.navItems.length;
         this.navItems.push({ kind: "option", option, parentValue });
       }
@@ -828,6 +1316,10 @@ var ForgeSelect = class {
         }
       }
     };
+    if (trimmedQuery !== "" && trimmedQuery.length < this.opts.minSearchLength) {
+      this.rows.push({ kind: "min-length" });
+      return;
+    }
     if (this.loading) {
       this.rows.push({ kind: "loading" });
       return;
@@ -855,16 +1347,30 @@ var ForgeSelect = class {
     else if (this.loadingMore) this.rows.push({ kind: "loading-more" });
   }
   hasExactMatch(lowerQuery) {
-    const matchesExactly = (option) => option.label.toLowerCase() === lowerQuery || (option.children ?? []).some(matchesExactly);
-    for (const item of this.data) {
-      const options = isGroup(item) ? item.options : [item];
-      if (options.some(matchesExactly)) return true;
-    }
-    return false;
+    return !!this.findOptionByLabel(lowerQuery);
   }
   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() {
+    const offsets = [0];
+    for (let i = 0; i < this.rows.length; i += 1) offsets.push(offsets[i] + this.measuredRowHeight(i));
+    return offsets;
+  }
   renderList() {
     this.buildRows();
     this.renderRows();
@@ -872,7 +1378,7 @@ var ForgeSelect = class {
   }
   announceStatus() {
     const first = this.rows[0];
-    const message = first?.kind === "loading" ? this.strings.loading : first?.kind === "error" ? this.strings.errorLoading : first?.kind === "empty" ? this.strings.noResults : "";
+    const message = this.hasReachedMaximum() ? format(this.strings.maximumSelected, { count: String(this.opts.maxSelections) }) : first?.kind === "loading" ? this.strings.loading : first?.kind === "error" ? this.strings.errorLoading : first?.kind === "empty" ? this.strings.noResults : first?.kind === "min-length" ? format(this.strings.minSearchLength, { count: String(this.opts.minSearchLength) }) : "";
     if (this.liveRegion.textContent !== message) this.liveRegion.textContent = message;
   }
   renderRows() {
@@ -881,26 +1387,40 @@ 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);
     }
     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);
+      if (this.opts.variableItemHeight) {
+        const measured = element.getBoundingClientRect().height || element.offsetHeight;
+        if (measured > 0) this.rowHeightCache.set(this.rowKey(this.rows[i], i), 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;
@@ -923,6 +1443,13 @@ var ForgeSelect = class {
         li.setAttribute("aria-selected", "false");
         li.textContent = this.strings.noResults;
         break;
+      case "min-length":
+        li.className = "forge-select__min-length";
+        li.setAttribute("role", "option");
+        li.setAttribute("aria-disabled", "true");
+        li.setAttribute("aria-selected", "false");
+        li.textContent = format(this.strings.minSearchLength, { count: String(this.opts.minSearchLength) });
+        break;
       case "error":
         li.className = "forge-select__error";
         li.setAttribute("role", "option");
@@ -952,17 +1479,20 @@ var ForgeSelect = class {
         break;
       case "option": {
         li.className = "forge-select__option";
+        li.dataset.optionValue = row.option.value;
+        if (row.option.className) li.classList.add(...row.option.className.trim().split(/\s+/).filter(Boolean));
         li.setAttribute("role", "option");
         const isSelected = this.selected.includes(row.option.value);
         li.setAttribute("aria-selected", String(isSelected));
         if (isSelected) li.classList.add("forge-select__option--selected");
-        if (this.opts.multiple && row.hasChildren && computeCheckState(row.option, this.selected) === "some") {
+        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))`;
         }
-        if (row.option.disabled) {
+        if (this.isOptionDisabled(row.option) || this.hasReachedMaximum() && !this.selected.includes(row.option.value)) {
           li.classList.add("forge-select__option--disabled");
           li.setAttribute("aria-disabled", "true");
         } else {
@@ -993,6 +1523,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");
@@ -1019,8 +1571,8 @@ var ForgeSelect = class {
         (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;
@@ -1085,7 +1637,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();
@@ -1094,6 +1646,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
@@ -1118,12 +1719,15 @@ var ForgeSelect = class {
     this.ajaxController = controller;
     const page = append ? this.page + 1 : 0;
     try {
-      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}`);
-      const 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))];
@@ -1148,7 +1752,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();
       }