forge-select 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -51,25 +51,44 @@ 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: {
     noResults: "No results found",
     loading: "Loading\u2026",
     loadingMore: "Loading more\u2026",
+    errorLoading: "Could not load options",
     createOption: 'Create "{query}"',
     clearSelection: "Clear selection",
     removeItem: "Remove {label}",
-    search: "Search"
+    search: "Search",
+    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",
     loading: "\u0110ang t\u1EA3i\u2026",
     loadingMore: "\u0110ang t\u1EA3i th\xEAm\u2026",
+    errorLoading: "Kh\xF4ng th\u1EC3 t\u1EA3i t\xF9y ch\u1ECDn",
     createOption: 'T\u1EA1o "{query}"',
     clearSelection: "X\xF3a l\u1EF1a ch\u1ECDn",
     removeItem: "X\xF3a {label}",
-    search: "T\xECm ki\u1EBFm"
+    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.",
+    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) {
@@ -82,39 +101,164 @@ function format(template, vars) {
   return template.replace(/\{(\w+)\}/g, (match, key) => vars[key] ?? match);
 }
 
-// src/ForgeSelect.ts
-var DEFAULT_ITEM_HEIGHT = 36;
-var VIRTUAL_BUFFER = 5;
-var VIRTUAL_THRESHOLD = 100;
-var ROW_CACHE_LIMIT = 2e3;
-var uidCounter = 0;
+// src/native-select.ts
+function parseNativeOptions(select) {
+  const data = [];
+  for (const child of Array.from(select.children)) {
+    if (child instanceof HTMLOptGroupElement) {
+      data.push({ label: child.label, options: Array.from(child.querySelectorAll("option")).map(parseOption) });
+    } else if (child instanceof HTMLOptionElement) {
+      data.push(parseOption(child));
+    }
+  }
+  return data;
+}
+function parseOption(option) {
+  const groupDisabled = option.parentElement instanceof HTMLOptGroupElement && option.parentElement.disabled;
+  return {
+    value: option.value,
+    label: option.textContent?.trim() ?? option.value,
+    disabled: option.disabled || groupDisabled || void 0
+  };
+}
+
+// src/option-renderer.ts
+function renderOptionContent(container, option, template, variant = "row") {
+  if (template) {
+    const result = template(option);
+    if (typeof result === "string") container.innerHTML = result;
+    else container.append(result);
+    return;
+  }
+  if (!option.avatar && !option.description) {
+    container.textContent = option.label;
+    return;
+  }
+  if (option.avatar) {
+    const avatar = document.createElement("img");
+    avatar.className = variant === "row" ? "forge-select__option-avatar" : "forge-select__inline-avatar";
+    avatar.src = option.avatar;
+    avatar.alt = "";
+    avatar.setAttribute("loading", "lazy");
+    avatar.setAttribute("decoding", "async");
+    container.append(avatar);
+  }
+  if (variant === "row" && option.description) {
+    const body = document.createElement("span");
+    body.className = "forge-select__option-body";
+    const label = document.createElement("span");
+    label.className = "forge-select__option-label";
+    label.textContent = option.label;
+    const description = document.createElement("span");
+    description.className = "forge-select__option-desc";
+    description.textContent = option.description;
+    body.append(label, description);
+    container.append(body);
+  } else {
+    const label = document.createElement("span");
+    label.className = "forge-select__option-label";
+    label.textContent = option.label;
+    container.append(label);
+  }
+}
+
+// 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();
+  for (const [key, value] of Object.entries(ajax.params(query, page))) params.set(key, String(value));
+  const separator = ajax.url.includes("?") ? "&" : "?";
+  return `${ajax.url}${separator}${params.toString()}`;
+}
+function normalizeRemoteResult(ajax, response) {
+  const result = ajax.transform ? ajax.transform(response) : response;
+  if (Array.isArray(result)) return { options: result, hasMore: false };
+  if (!result || !Array.isArray(result.options)) {
+    throw new Error(
+      "ForgeSelect: ajax.transform must return an array of options, or an object shaped like { options: Option[], hasMore?: boolean }."
+    );
+  }
+  return { options: result.options, hasMore: ajax.pagination ? Boolean(result.hasMore) : false };
+}
+
+// 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) {
-    values.push(child.value, ...collectDescendantValues(child));
+    if (!isDisabled(child)) values.push(child.value);
+    values.push(...collectDescendantValues(child, isDisabled));
   }
   return values;
 }
-function computeCheckState(option, selected) {
-  if (!option.children || option.children.length === 0) {
-    return selected.includes(option.value) ? "all" : "none";
-  }
-  const states = option.children.map((child) => computeCheckState(child, selected));
-  if (states.every((s) => s === "all")) return "all";
-  if (states.every((s) => s === "none")) return "none";
+function computeCheckState(option, selected, isDisabled = defaultIsDisabled) {
+  if (!option.children?.length) return selected.includes(option.value) ? "all" : "none";
+  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";
   return "some";
 }
+function findOption(items, value) {
+  const search = (options) => {
+    for (const option of options) {
+      if (option.value === value) return option;
+      const found = option.children ? search(option.children) : void 0;
+      if (found) return found;
+    }
+    return void 0;
+  };
+  for (const item of items) {
+    const found = search(isGroup(item) ? item.options : [item]);
+    if (found) return found;
+  }
+  return void 0;
+}
+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, 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);
+  };
+  for (const item of items) (isGroup(item) ? item.options : [item]).forEach(sync);
+}
+function collectValues(items) {
+  const values = /* @__PURE__ */ new Set();
+  const visit = (option) => {
+    values.add(option.value);
+    option.children?.forEach(visit);
+  };
+  for (const item of items) (isGroup(item) ? item.options : [item]).forEach(visit);
+  return values;
+}
+function arraysEqual(a, b) {
+  return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+// src/ForgeSelect.ts
+var DEFAULT_ITEM_HEIGHT = 36;
+var VIRTUAL_BUFFER = 5;
+var VIRTUAL_THRESHOLD = 100;
+var ROW_CACHE_LIMIT = 2e3;
+var uidCounter = 0;
 var ForgeSelect = class {
   constructor(target, options = {}) {
     this.selected = [];
     this.selectedOptions = /* @__PURE__ */ new Map();
+    this.suppressNextTagClick = false;
     this.emitter = new Emitter();
     this.uid = `forge-select-${++uidCounter}`;
     this.searchInput = null;
+    this.portalHost = null;
     this.isOpen = false;
     this.isDisabled = false;
     this.destroyed = false;
@@ -130,9 +274,43 @@ var ForgeSelect = class {
     this.hasMore = true;
     this.ajaxTimer = null;
     this.ajaxRequestId = 0;
+    this.ajaxController = null;
     this.remoteLoaded = false;
+    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.onNativeChange = () => {
+      if (!this.nativeSelect || this.destroyed || this.syncingNative) return;
+      const values = Array.from(this.nativeSelect.selectedOptions, (option) => option.value);
+      this.applyNativeValues(values);
+    };
+    this.onFormReset = () => {
+      if (!this.nativeSelect || this.destroyed) return;
+      const defaults = Array.from(this.nativeSelect.options).filter((option) => option.defaultSelected).map((option) => option.value);
+      this.applyNativeValues(defaults);
     };
     const el = typeof target === "string" ? document.querySelector(target) : target;
     if (!el) {
@@ -140,36 +318,63 @@ var ForgeSelect = class {
     }
     this.el = el;
     const nativeSelect = el instanceof HTMLSelectElement ? el : null;
+    this.nativeSelect = nativeSelect;
+    this.nativeForm = nativeSelect?.form ?? null;
+    this.originalDisplay = el.style.display;
+    this.originalDisabled = nativeSelect?.disabled ?? false;
     this.opts = {
       placeholder: options.placeholder ?? "",
       searchable: options.searchable ?? true,
       multiple: options.multiple ?? nativeSelect?.multiple ?? false,
       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 ?? false,
+      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,
+      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,
       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) {
-      for (const option of Array.from(nativeSelect.querySelectorAll("option"))) {
-        if (option.hasAttribute("selected")) this.selectValue(option.value, false);
+      const nativeOptions = Array.from(nativeSelect.options);
+      const hasIntentionalSelection = nativeSelect.multiple || nativeSelect.selectedIndex > 0 || nativeOptions.some((option) => option.defaultSelected);
+      for (const option of nativeOptions) {
+        if (hasIntentionalSelection && option.selected) this.selectValue(option.value, false);
       }
     }
     this.buildDom();
     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);
   }
+  applyNativeValues(values) {
+    this.selected = [];
+    for (const value of this.opts.multiple ? values : values.slice(0, 1)) this.selectValue(value, false);
+    this.renderValue();
+    if (this.isOpen) this.renderList();
+    this.emitter.emit("change", this.getValue());
+  }
   // ---------------------------------------------------------------- public API
   open() {
     if (this.isOpen || this.isDisabled || this.destroyed) return;
@@ -182,7 +387,10 @@ var ForgeSelect = class {
       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);
   }
@@ -191,8 +399,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 = "";
@@ -201,34 +412,104 @@ 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();
     for (const plugin of this.plugins) plugin.onDestroy?.(this);
     this.destroyed = true;
     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.portalHost?.remove();
     this.root.remove();
-    this.el.style.display = "";
+    this.el.style.display = this.originalDisplay;
+    if (this.nativeSelect) this.nativeSelect.disabled = this.originalDisabled;
     this.emitter.clear();
   }
   getValue() {
     if (this.opts.multiple) return [...this.selected];
     return this.selected[0] ?? null;
   }
-  setValue(value) {
+  setValue(value, options = {}) {
     const values = value == null ? [] : Array.isArray(value) ? value : [value];
     const next = this.opts.multiple ? values : values.slice(0, 1);
     if (arraysEqual(next, this.selected)) return;
     this.selected = [];
     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.loading = 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.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");
     this.control.tabIndex = 0;
     this.control.setAttribute("aria-disabled", "false");
+    if (this.nativeSelect) this.nativeSelect.disabled = false;
   }
   disable() {
     this.close();
@@ -236,6 +517,7 @@ var ForgeSelect = class {
     this.root.classList.add("forge-select--disabled");
     this.control.tabIndex = -1;
     this.control.setAttribute("aria-disabled", "true");
+    if (this.nativeSelect) this.nativeSelect.disabled = true;
   }
   on(event, handler) {
     this.emitter.on(event, handler);
@@ -244,18 +526,59 @@ var ForgeSelect = class {
     this.emitter.off(event, handler);
   }
   // ---------------------------------------------------------------- DOM setup
+  /**
+   * The original target (a hidden native <select> or a plain mount div) can
+   * carry an accessible name via aria-label/aria-labelledby, or via a
+   * <label for> pointing at its id — but once `this.el` is display:none it
+   * drops out of the accessibility tree, so any such association silently
+   * stops reaching assistive tech unless we forward it onto the visible,
+   * interactive `this.control` ourselves.
+   */
+  applyAccessibleName() {
+    const ariaLabelledby = this.el.getAttribute("aria-labelledby");
+    const ariaLabel = this.el.getAttribute("aria-label");
+    if (ariaLabelledby) {
+      this.control.setAttribute("aria-labelledby", ariaLabelledby);
+    } else if (ariaLabel) {
+      this.control.setAttribute("aria-label", ariaLabel);
+    } else if (this.el.id) {
+      const label = Array.from(document.getElementsByTagName("label")).find((el) => el.htmlFor === this.el.id);
+      if (label) {
+        if (!label.id) label.id = `${this.uid}-label`;
+        this.control.setAttribute("aria-labelledby", label.id);
+      }
+    }
+  }
+  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;
     this.root.style.setProperty("--fs-item-height", `${this.opts.itemHeight}px`);
+    if (this.opts.sortable && this.opts.multiple) this.root.classList.add("forge-select--sortable");
     this.control = document.createElement("div");
     this.control.className = "forge-select__control";
     this.control.setAttribute("role", "combobox");
     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");
     this.valueEl.className = "forge-select__value";
     this.clearBtn = document.createElement("button");
@@ -278,6 +601,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");
@@ -286,18 +610,45 @@ var ForgeSelect = class {
     this.list.setAttribute("role", "listbox");
     if (this.opts.multiple) this.list.setAttribute("aria-multiselectable", "true");
     this.dropdown.append(this.list);
-    this.root.append(this.control, this.dropdown);
+    this.liveRegion = document.createElement("div");
+    this.liveRegion.className = "forge-select__sr-only";
+    this.liveRegion.setAttribute("role", "status");
+    this.liveRegion.setAttribute("aria-live", "polite");
+    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() {
     this.control.addEventListener("click", (event) => {
       if (event.target === this.clearBtn) return;
+      if (this.suppressNextTagClick) {
+        this.suppressNextTagClick = false;
+        return;
+      }
       if (this.isDisabled) return;
-      this.isOpen ? this.close() : this.open();
+      if (this.isOpen) this.close();
+      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();
@@ -308,13 +659,45 @@ var ForgeSelect = class {
         this.highlightedIndex = -1;
         this.list.scrollTop = 0;
         this.emitter.emit("search", this.query);
-        if (this.opts.ajax) {
+        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.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;
@@ -327,7 +710,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);
     });
@@ -366,42 +754,73 @@ var ForgeSelect = class {
           this.control.focus();
         }
         break;
+      case "ArrowRight":
+        if (this.isOpen && this.navigateTree("right")) event.preventDefault();
+        break;
+      case "ArrowLeft":
+        if (this.isOpen && this.navigateTree("left")) event.preventDefault();
+        break;
       case "Tab":
         this.close();
         break;
     }
   }
   // ---------------------------------------------------------------- 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
@@ -410,18 +829,7 @@ var ForgeSelect = class {
    * No-op for data with no `children` anywhere.
    */
   syncTreeAncestors() {
-    const sync = (option) => {
-      if (!option.children || option.children.length === 0) return;
-      for (const child of option.children) sync(child);
-      const state = computeCheckState(option, this.selected);
-      const index = this.selected.indexOf(option.value);
-      if (state === "all" && index === -1) this.selected.push(option.value);
-      else if (state !== "all" && index !== -1) this.selected.splice(index, 1);
-    };
-    for (const item of this.data) {
-      const options = isGroup(item) ? item.options : [item];
-      options.forEach(sync);
-    }
+    syncTreeAncestors(this.data, this.selected, this.isOptionDisabled);
   }
   clearSelection() {
     if (this.selected.length === 0) return;
@@ -429,13 +837,26 @@ var ForgeSelect = class {
     this.emitter.emit("clear");
     this.afterSelectionChange();
   }
-  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();
+    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();
-    this.emitter.emit("change", this.getValue());
+    if (emitChange) this.emitter.emit("change", this.getValue());
   }
-  syncNativeSelect() {
+  syncNativeSelect(dispatchChange = true) {
     if (!(this.el instanceof HTMLSelectElement)) return;
     const existing = /* @__PURE__ */ new Set();
     for (const option of Array.from(this.el.options)) {
@@ -450,16 +871,30 @@ var ForgeSelect = class {
       option.selected = true;
       this.el.append(option);
     }
-    this.el.dispatchEvent(new Event("change", { bubbles: true }));
+    if (this.opts.sortable && this.opts.multiple) {
+      for (const value of this.selected) {
+        const option = Array.from(this.el.options).find((o) => o.value === value);
+        if (option) this.el.append(option);
+      }
+    }
+    if (!dispatchChange) return;
+    this.syncingNative = true;
+    try {
+      this.el.dispatchEvent(new Event("change", { bubbles: true }));
+    } finally {
+      this.syncingNative = false;
+    }
   }
   findOption(value) {
+    return findOption(this.data, value);
+  }
+  findOptionByLabel(label) {
+    const lower = label.toLowerCase();
     const search = (options) => {
       for (const option of options) {
-        if (option.value === value) return option;
-        if (option.children) {
-          const found = search(option.children);
-          if (found) return found;
-        }
+        if (option.label.toLowerCase() === lower) return option;
+        const found = option.children ? search(option.children) : void 0;
+        if (found) return found;
       }
       return void 0;
     };
@@ -469,17 +904,42 @@ var ForgeSelect = class {
     }
     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];
@@ -490,7 +950,17 @@ var ForgeSelect = class {
     }
     const { value } = item.option;
     if (this.opts.multiple) {
-      this.selected.includes(value) ? this.deselectValue(value, true) : 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();
@@ -516,7 +986,7 @@ var ForgeSelect = class {
         tag.className = "forge-select__tag";
         const label = document.createElement("span");
         label.className = "forge-select__tag-label";
-        this.renderTemplate(label, option, this.opts.templateSelection, "inline");
+        renderOptionContent(label, option, this.opts.templateSelection, "inline");
         const remove = document.createElement("button");
         remove.type = "button";
         remove.className = "forge-select__tag-remove";
@@ -527,6 +997,14 @@ var ForgeSelect = class {
           if (!this.isDisabled) this.deselectValue(value, true);
         });
         tag.append(label, remove);
+        if (this.opts.sortable) {
+          tag.dataset.value = value;
+          tag.tabIndex = 0;
+          tag.setAttribute("aria-roledescription", "draggable item");
+          tag.setAttribute("aria-label", format(this.strings.reorderHint, { label: option.label }));
+          tag.addEventListener("keydown", (event) => this.handleTagKeydown(event, value));
+          this.bindTagDrag(tag, value);
+        }
         this.valueEl.append(tag);
       }
     } else {
@@ -536,59 +1014,116 @@ var ForgeSelect = class {
       };
       const span = document.createElement("span");
       span.className = "forge-select__single-value";
-      this.renderTemplate(span, option, this.opts.templateSelection, "inline");
+      renderOptionContent(span, option, this.opts.templateSelection, "inline");
       this.valueEl.append(span);
     }
   }
-  renderTemplate(container, option, template, variant = "row") {
-    if (template) {
-      const result = template(option);
-      if (typeof result === "string") container.innerHTML = result;
-      else container.append(result);
-      return;
-    }
-    if (!option.avatar && !option.description) {
-      container.textContent = option.label;
-      return;
-    }
-    if (option.avatar) {
-      const avatar = document.createElement("img");
-      avatar.className = variant === "row" ? "forge-select__option-avatar" : "forge-select__inline-avatar";
-      avatar.src = option.avatar;
-      avatar.alt = "";
-      avatar.setAttribute("loading", "lazy");
-      avatar.setAttribute("decoding", "async");
-      container.append(avatar);
-    }
-    if (variant === "row" && option.description) {
-      const body = document.createElement("span");
-      body.className = "forge-select__option-body";
-      const label = document.createElement("span");
-      label.className = "forge-select__option-label";
-      label.textContent = option.label;
-      const desc = document.createElement("span");
-      desc.className = "forge-select__option-desc";
-      desc.textContent = option.description;
-      body.append(label, desc);
-      container.append(body);
-    } else {
-      const label = document.createElement("span");
-      label.className = "forge-select__option-label";
-      label.textContent = option.label;
-      container.append(label);
+  /**
+   * Pointer-based (mouse/touch/pen) reorder for a single tag. Only the real
+   * dragged DOM node is moved during the gesture — a full renderValue()
+   * mid-drag would destroy it — so the reordered `this.selected` is only
+   * committed on release. The move/up listeners and pointer capture live on
+   * the stable `this.valueEl` container rather than the tag itself: `tag`
+   * gets repositioned via `insertBefore` during the drag, and browsers treat
+   * that reparenting as detaching the node, which silently drops pointer
+   * capture (and further move events) if it were captured on `tag`.
+   */
+  bindTagDrag(tag, value) {
+    const DRAG_THRESHOLD = 4;
+    let startX = 0;
+    let dragging = false;
+    let order = [];
+    const onPointerMove = (event) => {
+      if (!dragging) {
+        if (Math.abs(event.clientX - startX) < DRAG_THRESHOLD) return;
+        dragging = true;
+        order = [...this.selected];
+        if (typeof this.valueEl.setPointerCapture === "function") {
+          this.valueEl.setPointerCapture(event.pointerId);
+        }
+        tag.classList.add("forge-select__tag--dragging");
+      }
+      event.preventDefault();
+      const draggedIndex = order.indexOf(value);
+      const siblings = Array.from(this.valueEl.querySelectorAll(".forge-select__tag"));
+      for (const sibling of siblings) {
+        if (sibling === tag) continue;
+        const siblingValue = sibling.dataset.value;
+        if (!siblingValue) continue;
+        const siblingIndex = order.indexOf(siblingValue);
+        if (siblingIndex === -1) continue;
+        const rect = sibling.getBoundingClientRect();
+        const midX = rect.left + rect.width / 2;
+        const movingRight = draggedIndex < siblingIndex;
+        const crossed = movingRight ? event.clientX > midX : event.clientX < midX;
+        if (!crossed) continue;
+        order.splice(draggedIndex, 1);
+        order.splice(siblingIndex, 0, value);
+        if (movingRight) this.valueEl.insertBefore(tag, sibling.nextSibling);
+        else this.valueEl.insertBefore(tag, sibling);
+        break;
+      }
+    };
+    const finishDrag = (event) => {
+      this.valueEl.removeEventListener("pointermove", onPointerMove);
+      this.valueEl.removeEventListener("pointerup", finishDrag);
+      this.valueEl.removeEventListener("pointercancel", finishDrag);
+      if (!dragging) return;
+      if (typeof this.valueEl.releasePointerCapture === "function") {
+        this.valueEl.releasePointerCapture(event.pointerId);
+      }
+      tag.classList.remove("forge-select__tag--dragging");
+      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;
+      if (event.target.closest(".forge-select__tag-remove")) return;
+      startX = event.clientX;
+      dragging = false;
+      this.valueEl.addEventListener("pointermove", onPointerMove);
+      this.valueEl.addEventListener("pointerup", finishDrag);
+      this.valueEl.addEventListener("pointercancel", finishDrag);
+    });
+  }
+  /** Alt+Left/Alt+Right on a focused tag: the keyboard-operable equivalent of dragging. */
+  handleTagKeydown(event, value) {
+    if (!event.altKey || event.key !== "ArrowLeft" && event.key !== "ArrowRight") return;
+    const index = this.selected.indexOf(value);
+    const targetIndex = event.key === "ArrowLeft" ? index - 1 : index + 1;
+    if (index === -1 || targetIndex < 0 || targetIndex >= this.selected.length) return;
+    event.preventDefault();
+    event.stopPropagation();
+    const next = [...this.selected];
+    [next[index], next[targetIndex]] = [next[targetIndex], next[index]];
+    this.selected = next;
+    this.afterSelectionChange();
+    this.emitter.emit("reorder", [...this.selected]);
+    this.focusTagByValue(value);
+  }
+  focusTagByValue(value) {
+    for (const tag of Array.from(this.valueEl.querySelectorAll(".forge-select__tag"))) {
+      if (tag.dataset.value === value) {
+        tag.focus();
+        return;
+      }
     }
   }
   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 = 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 subtreeMatches = (option) => query === "" || matches(option) || (option.children ?? []).some(subtreeMatches);
-    const pushOption = (option, depth) => {
+    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 });
+        this.navItems.push({ kind: "option", option, parentValue });
       }
       const hasChildren = !!option.children && option.children.length > 0;
       this.rows.push({ kind: "option", option, navIndex, depth, hasChildren });
@@ -596,15 +1131,23 @@ var ForgeSelect = class {
         const expanded = query !== "" || this.expandedValues.has(option.value);
         if (expanded) {
           for (const child of option.children) {
-            if (subtreeMatches(child)) pushOption(child, depth + 1);
+            if (subtreeMatches(child)) pushOption(child, depth + 1, option.value);
           }
         }
       }
     };
+    if (trimmedQuery !== "" && trimmedQuery.length < this.opts.minSearchLength) {
+      this.rows.push({ kind: "min-length" });
+      return;
+    }
     if (this.loading) {
       this.rows.push({ kind: "loading" });
       return;
     }
+    if (this.loadError) {
+      this.rows.push({ kind: "error" });
+      return;
+    }
     for (const item of this.data) {
       if (isGroup(item)) {
         const visible = item.options.filter(subtreeMatches);
@@ -624,12 +1167,7 @@ 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;
@@ -637,6 +1175,12 @@ var ForgeSelect = class {
   renderList() {
     this.buildRows();
     this.renderRows();
+    this.announceStatus();
+  }
+  announceStatus() {
+    const first = this.rows[0];
+    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() {
     const scrollTop = this.list.scrollTop;
@@ -681,10 +1225,30 @@ var ForgeSelect = class {
         break;
       case "empty":
         li.className = "forge-select__empty";
+        li.setAttribute("role", "option");
+        li.setAttribute("aria-disabled", "true");
+        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");
+        li.setAttribute("aria-disabled", "true");
+        li.setAttribute("aria-selected", "false");
+        li.textContent = this.strings.errorLoading;
+        break;
       case "loading":
         li.className = "forge-select__loading";
+        li.setAttribute("role", "option");
+        li.setAttribute("aria-disabled", "true");
+        li.setAttribute("aria-selected", "false");
         li.textContent = this.strings.loading;
         break;
       case "loading-more":
@@ -702,17 +1266,19 @@ 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");
         }
         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 {
@@ -721,11 +1287,13 @@ var ForgeSelect = class {
           if (row.navIndex === this.highlightedIndex) li.classList.add("forge-select__option--highlighted");
         }
         if (row.hasChildren) {
+          const expanded = this.query !== "" || this.expandedValues.has(row.option.value);
+          li.setAttribute("aria-expanded", String(expanded));
           const twisty = document.createElement("span");
           twisty.className = "forge-select__twisty";
           twisty.dataset.twisty = row.option.value;
           twisty.setAttribute("aria-hidden", "true");
-          twisty.textContent = this.expandedValues.has(row.option.value) ? "\u25BC" : "\u25B6";
+          twisty.textContent = expanded ? "\u25BC" : "\u25B6";
           li.append(twisty);
         }
         li.append(this.optionContent(row.option));
@@ -745,7 +1313,7 @@ var ForgeSelect = class {
     if (!cached) {
       const holder = document.createElement("span");
       holder.className = "forge-select__option-content";
-      this.renderTemplate(holder, option, this.opts.templateResult);
+      renderOptionContent(holder, option, this.opts.templateResult);
       if (this.rowContentCache.size >= ROW_CACHE_LIMIT) {
         const oldest = this.rowContentCache.keys().next().value;
         this.rowContentCache.delete(oldest);
@@ -757,7 +1325,10 @@ var ForgeSelect = class {
   }
   moveHighlight(delta) {
     if (this.navItems.length === 0) return;
-    const next = this.highlightedIndex === -1 && delta > 0 ? 0 : (this.highlightedIndex + delta + this.navItems.length) % this.navItems.length;
+    const next = this.highlightedIndex === -1 ? delta > 0 ? 0 : this.navItems.length - 1 : (this.highlightedIndex + delta + this.navItems.length) % this.navItems.length;
+    this.focusNavIndex(next);
+  }
+  focusNavIndex(next) {
     this.highlightedIndex = next;
     if (this.usesVirtualScroll()) {
       const rowIndex = this.rows.findIndex(
@@ -779,6 +1350,41 @@ var ForgeSelect = class {
       highlighted?.scrollIntoView?.({ block: "nearest" });
     }
   }
+  navigateTree(direction) {
+    const item = this.navItems[this.highlightedIndex];
+    if (!item || item.kind !== "option") return false;
+    const { option, parentValue } = item;
+    const hasChildren = !!option.children?.length;
+    const expanded = this.query !== "" || this.expandedValues.has(option.value);
+    if (direction === "right") {
+      if (hasChildren && !expanded) {
+        this.expandedValues.add(option.value);
+        this.renderList();
+        return true;
+      }
+      if (hasChildren) {
+        const childIndex = this.navItems.findIndex((nav) => nav.kind === "option" && nav.parentValue === option.value);
+        if (childIndex >= 0) {
+          this.focusNavIndex(childIndex);
+          return true;
+        }
+      }
+      return false;
+    }
+    if (hasChildren && expanded && this.query === "") {
+      this.expandedValues.delete(option.value);
+      this.renderList();
+      return true;
+    }
+    if (parentValue) {
+      const parentIndex = this.navItems.findIndex((nav) => nav.kind === "option" && nav.option.value === parentValue);
+      if (parentIndex >= 0) {
+        this.focusNavIndex(parentIndex);
+        return true;
+      }
+    }
+    return false;
+  }
   updateActiveDescendant() {
     const target = this.searchInput ?? this.control;
     if (this.highlightedIndex >= 0) {
@@ -790,12 +1396,18 @@ var ForgeSelect = class {
   // ---------------------------------------------------------------- remote data
   scheduleRemoteLoad(query, delay) {
     if (this.ajaxTimer) clearTimeout(this.ajaxTimer);
+    const requestId = ++this.ajaxRequestId;
+    this.ajaxController?.abort();
+    this.ajaxController = null;
     this.page = 0;
     this.hasMore = true;
     this.loading = true;
+    this.loadingMore = false;
+    this.loadError = null;
     this.renderList();
     this.ajaxTimer = setTimeout(() => {
-      void this.loadRemote(query);
+      this.ajaxTimer = null;
+      void this.loadRemote(query, { requestId });
     }, delay);
   }
   /**
@@ -813,18 +1425,26 @@ var ForgeSelect = class {
     this.renderList();
     void this.loadRemote(this.query, { append: true });
   }
-  async loadRemote(query, { append = false } = {}) {
+  async loadRemote(query, { append = false, requestId } = {}) {
     const ajax = this.opts.ajax;
-    const requestId = ++this.ajaxRequestId;
+    const activeRequestId = requestId ?? ++this.ajaxRequestId;
+    if (activeRequestId !== this.ajaxRequestId) return;
+    this.ajaxController?.abort();
+    const controller = new AbortController();
+    this.ajaxController = controller;
     const page = append ? this.page + 1 : 0;
     try {
-      const url = buildUrl(ajax, query, page);
-      const response = await fetch(url);
-      const json = await response.json();
-      if (requestId !== this.ajaxRequestId || this.destroyed) return;
-      const result = ajax.transform ? ajax.transform(json) : json;
-      const options = Array.isArray(result) ? result : result.options;
-      const hasMore = ajax.pagination ? Array.isArray(result) ? false : result.hasMore : false;
+      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();
+      }
+      if (activeRequestId !== this.ajaxRequestId || this.destroyed) return;
+      const { options, hasMore } = normalizeRemoteResult(ajax, json);
       if (append) {
         const existing = collectValues(this.data);
         this.data = [...this.data, ...options.filter((o) => !existing.has(o.value))];
@@ -835,15 +1455,20 @@ var ForgeSelect = class {
       this.page = page;
       this.hasMore = hasMore;
       this.remoteLoaded = true;
-    } catch {
-      if (requestId !== this.ajaxRequestId || this.destroyed) return;
+      this.loadError = null;
+    } catch (cause) {
+      if (activeRequestId !== this.ajaxRequestId || this.destroyed || controller.signal.aborted) return;
+      const error = cause instanceof Error ? cause : new Error(String(cause));
       if (!append) {
         this.data = [];
         this.rowContentCache.clear();
       }
       this.hasMore = false;
+      this.loadError = error;
+      this.emitter.emit("error", error);
     } finally {
-      if (requestId === this.ajaxRequestId && !this.destroyed) {
+      if (activeRequestId === this.ajaxRequestId && !this.destroyed) {
+        this.ajaxController = null;
         this.loading = false;
         this.loadingMore = false;
         if (this.isOpen) this.renderList();
@@ -851,51 +1476,6 @@ var ForgeSelect = class {
     }
   }
 };
-function parseNativeOptions(select) {
-  const data = [];
-  for (const child of Array.from(select.children)) {
-    if (child instanceof HTMLOptGroupElement) {
-      data.push({
-        label: child.label,
-        options: Array.from(child.querySelectorAll("option")).map(parseOption)
-      });
-    } else if (child instanceof HTMLOptionElement) {
-      data.push(parseOption(child));
-    }
-  }
-  return data;
-}
-function parseOption(option) {
-  return {
-    value: option.value,
-    label: option.textContent?.trim() ?? option.value,
-    disabled: option.disabled || void 0
-  };
-}
-function buildUrl(ajax, query, page) {
-  if (typeof ajax.url === "function") return ajax.url(query);
-  if (!ajax.params) return ajax.url;
-  const params = new URLSearchParams();
-  for (const [key, value] of Object.entries(ajax.params(query, page))) {
-    params.set(key, String(value));
-  }
-  const separator = ajax.url.includes("?") ? "&" : "?";
-  return `${ajax.url}${separator}${params.toString()}`;
-}
-function collectValues(items) {
-  const values = /* @__PURE__ */ new Set();
-  for (const item of items) {
-    if (isGroup(item)) {
-      for (const option of item.options) values.add(option.value);
-    } else {
-      values.add(item.value);
-    }
-  }
-  return values;
-}
-function arraysEqual(a, b) {
-  return a.length === b.length && a.every((value, index) => value === b[index]);
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ForgeSelect