forge-select 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -56,18 +56,24 @@ 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."
   },
   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."
   }
 };
 function getStrings(language) {
@@ -80,19 +86,158 @@ function format(template, vars) {
   return template.replace(/\{(\w+)\}/g, (match, key) => vars[key] ?? match);
 }
 
+// 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 (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) {
+  if (!option.children) return [];
+  const values = [];
+  for (const child of option.children) {
+    if (!child.disabled) values.push(child.value);
+    values.push(...collectDescendantValues(child));
+  }
+  return values;
+}
+function computeCheckState(option, selected) {
+  if (!option.children?.length) return selected.includes(option.value) ? "all" : "none";
+  const states = option.children.filter((child) => !child.disabled).map((child) => computeCheckState(child, selected));
+  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) {
+  const sync = (option) => {
+    if (!option.children?.length) return;
+    for (const child of option.children) sync(child);
+    const state = computeCheckState(option, selected);
+    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;
-function isGroup(item) {
-  return item.options !== void 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;
@@ -104,27 +249,53 @@ var ForgeSelect = class {
     this.navItems = [];
     this.highlightedIndex = -1;
     this.rowContentCache = /* @__PURE__ */ new Map();
+    this.expandedValues = /* @__PURE__ */ new Set();
     this.loading = false;
+    this.loadingMore = false;
+    this.page = 0;
+    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;
     this.onDocumentMouseDown = (event) => {
       if (!this.root.contains(event.target)) this.close();
     };
+    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) {
       throw new Error(`ForgeSelect: target element not found: ${String(target)}`);
     }
     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,
       theme: options.theme ?? "default",
-      disabled: options.disabled ?? false,
+      disabled: options.disabled ?? nativeSelect?.disabled ?? false,
       data: options.data,
       ajax: options.ajax,
       templateResult: options.templateResult,
@@ -138,15 +309,26 @@ var ForgeSelect = class {
     this.plugins = this.opts.plugins;
     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);
+    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;
@@ -184,28 +366,33 @@ var ForgeSelect = class {
     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.nativeForm?.removeEventListener("reset", this.onFormReset);
     this.rowContentCache.clear();
     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();
+    this.afterSelectionChange(options.emitChange ?? true);
   }
   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();
@@ -213,6 +400,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);
@@ -221,11 +409,35 @@ 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);
+      }
+    }
+  }
   buildDom() {
     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");
@@ -233,6 +445,7 @@ var ForgeSelect = class {
     this.control.setAttribute("aria-expanded", "false");
     this.control.setAttribute("aria-controls", `${this.uid}-list`);
     this.control.tabIndex = 0;
+    this.applyAccessibleName();
     this.valueEl = document.createElement("div");
     this.valueEl.className = "forge-select__value";
     this.clearBtn = document.createElement("button");
@@ -263,7 +476,11 @@ 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.dropdown, this.liveRegion);
     this.el.style.display = "none";
     this.el.insertAdjacentElement("afterend", this.root);
     this.bindEvents();
@@ -271,8 +488,13 @@ var ForgeSelect = class {
   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.clearBtn.addEventListener("click", (event) => {
@@ -294,13 +516,23 @@ var ForgeSelect = class {
       this.searchInput.addEventListener("keydown", (event) => this.handleKeydown(event));
     }
     this.list.addEventListener("click", (event) => {
-      const li = event.target.closest("li[data-nav-index]");
+      const target = event.target;
+      const twisty = target.closest("[data-twisty]");
+      if (twisty) {
+        const value = twisty.dataset.twisty;
+        if (this.expandedValues.has(value)) this.expandedValues.delete(value);
+        else this.expandedValues.add(value);
+        this.renderList();
+        return;
+      }
+      const li = target.closest("li[data-nav-index]");
       if (!li) return;
       const navIndex = Number(li.dataset.navIndex);
       this.activateNavItem(navIndex);
     });
     this.list.addEventListener("scroll", () => {
       if (this.usesVirtualScroll()) this.renderRows();
+      this.maybeLoadNextPage();
     });
   }
   handleKeydown(event) {
@@ -333,6 +565,12 @@ 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;
@@ -343,29 +581,55 @@ var ForgeSelect = class {
     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);
-    else this.selected = [value];
+    if (this.opts.multiple) {
+      this.selected.push(value);
+      for (const v of collectDescendantValues(option)) {
+        if (!this.selected.includes(v)) this.selected.push(v);
+      }
+      this.syncTreeAncestors();
+    } else {
+      this.selected = [value];
+    }
     if (notify) this.afterSelectionChange();
   }
   deselectValue(value, notify) {
     const index = this.selected.indexOf(value);
     if (index === -1) return;
     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)) {
+          const i = this.selected.indexOf(v);
+          if (i !== -1) this.selected.splice(i, 1);
+        }
+      }
+      this.syncTreeAncestors();
+    }
     if (notify) this.afterSelectionChange();
   }
+  /**
+   * Keeps every tree parent's own membership in `selected` consistent with
+   * its descendants (post-order, so parents see already-corrected children):
+   * a parent counts as selected only when `computeCheckState` says "all".
+   * No-op for data with no `children` anywhere.
+   */
+  syncTreeAncestors() {
+    syncTreeAncestors(this.data, this.selected);
+  }
   clearSelection() {
     if (this.selected.length === 0) return;
     this.selected = [];
     this.emitter.emit("clear");
     this.afterSelectionChange();
   }
-  afterSelectionChange() {
+  afterSelectionChange(emitChange = true) {
     this.renderValue();
-    this.syncNativeSelect();
+    this.syncNativeSelect(emitChange);
     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)) {
@@ -380,18 +644,22 @@ var ForgeSelect = class {
       option.selected = true;
       this.el.append(option);
     }
-    this.el.dispatchEvent(new Event("change", { bubbles: true }));
-  }
-  findOption(value) {
-    for (const item of this.data) {
-      if (isGroup(item)) {
-        const found = item.options.find((o) => o.value === value);
-        if (found) return found;
-      } else if (item.value === value) {
-        return item;
+    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);
       }
     }
-    return void 0;
+    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);
   }
   createFromQuery() {
     const label = this.query.trim();
@@ -414,7 +682,8 @@ var ForgeSelect = class {
     }
     const { value } = item.option;
     if (this.opts.multiple) {
-      this.selected.includes(value) ? this.deselectValue(value, true) : this.selectValue(value, true);
+      if (this.selected.includes(value)) this.deselectValue(value, true);
+      else this.selectValue(value, true);
     } else {
       this.selectValue(value, true);
       this.close();
@@ -440,7 +709,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";
@@ -451,6 +720,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 {
@@ -460,46 +737,99 @@ 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();
+    };
+    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.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() {
@@ -507,26 +837,40 @@ var ForgeSelect = class {
     this.navItems = [];
     const query = this.query.trim().toLowerCase();
     const matches = (option) => query === "" || option.label.toLowerCase().includes(query) || (option.description?.toLowerCase().includes(query) ?? false);
-    const pushOption = (option) => {
+    const subtreeMatches = (option) => query === "" || matches(option) || (option.children ?? []).some(subtreeMatches);
+    const pushOption = (option, depth, parentValue) => {
       let navIndex = -1;
       if (!option.disabled) {
         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 });
+      if (hasChildren) {
+        const expanded = query !== "" || this.expandedValues.has(option.value);
+        if (expanded) {
+          for (const child of option.children) {
+            if (subtreeMatches(child)) pushOption(child, depth + 1, option.value);
+          }
+        }
       }
-      this.rows.push({ kind: "option", option, navIndex });
     };
     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(matches);
+        const visible = item.options.filter(subtreeMatches);
         if (visible.length === 0) continue;
         this.rows.push({ kind: "group", label: item.label });
-        visible.forEach(pushOption);
-      } else if (matches(item)) {
-        pushOption(item);
+        visible.forEach((o) => pushOption(o, 0));
+      } else if (subtreeMatches(item)) {
+        pushOption(item, 0);
       }
     }
     if (this.opts.allowCreate && query !== "" && !this.hasExactMatch(query)) {
@@ -535,11 +879,13 @@ var ForgeSelect = class {
       this.rows.push({ kind: "create", navIndex });
     }
     if (this.rows.length === 0) this.rows.push({ kind: "empty" });
+    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((o) => o.label.toLowerCase() === lowerQuery)) return true;
+      if (options.some(matchesExactly)) return true;
     }
     return false;
   }
@@ -549,6 +895,12 @@ var ForgeSelect = class {
   renderList() {
     this.buildRows();
     this.renderRows();
+    this.announceStatus();
+  }
+  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 : "";
+    if (this.liveRegion.textContent !== message) this.liveRegion.textContent = message;
   }
   renderRows() {
     const scrollTop = this.list.scrollTop;
@@ -593,12 +945,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 "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":
+        li.className = "forge-select__loading-more";
+        li.setAttribute("aria-hidden", "true");
+        li.textContent = this.strings.loadingMore;
+        break;
       case "create":
         li.className = "forge-select__option forge-select__option--create";
         li.setAttribute("role", "option");
@@ -613,6 +983,12 @@ var ForgeSelect = class {
         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") {
+          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) {
           li.classList.add("forge-select__option--disabled");
           li.setAttribute("aria-disabled", "true");
@@ -621,6 +997,16 @@ var ForgeSelect = class {
           li.dataset.navIndex = String(row.navIndex);
           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 = expanded ? "\u25BC" : "\u25B6";
+          li.append(twisty);
+        }
         li.append(this.optionContent(row.option));
         break;
       }
@@ -638,7 +1024,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);
@@ -650,7 +1036,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(
@@ -672,6 +1061,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) {
@@ -683,69 +1107,81 @@ 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);
   }
-  async loadRemote(query) {
+  /**
+   * Fires on every list scroll. Only acts when pagination is opted into via
+   * `ajax.pagination`; reads real scroll geometry rather than row counts so
+   * it works whether or not virtual scrolling is active for this list.
+   */
+  maybeLoadNextPage() {
+    const ajax = this.opts.ajax;
+    if (!ajax?.pagination || !this.hasMore || this.loading || this.loadingMore) return;
+    const { scrollHeight, scrollTop, clientHeight } = this.list;
+    const threshold = this.opts.itemHeight * 2;
+    if (scrollHeight - scrollTop - clientHeight >= threshold) return;
+    this.loadingMore = true;
+    this.renderList();
+    void this.loadRemote(this.query, { append: true });
+  }
+  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);
-      const response = await fetch(url);
+      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();
-      if (requestId !== this.ajaxRequestId || this.destroyed) return;
-      this.data = ajax.transform ? ajax.transform(json) : json;
-      this.rowContentCache.clear();
+      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))];
+      } else {
+        this.data = options;
+        this.rowContentCache.clear();
+      }
+      this.page = page;
+      this.hasMore = hasMore;
       this.remoteLoaded = true;
-    } catch {
-      if (requestId !== this.ajaxRequestId || this.destroyed) return;
-      this.data = [];
-      this.rowContentCache.clear();
+      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();
       }
     }
   }
 };
-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) {
-  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))) {
-    params.set(key, String(value));
-  }
-  const separator = ajax.url.includes("?") ? "&" : "?";
-  return `${ajax.url}${separator}${params.toString()}`;
-}
-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