forge-select 0.7.0 → 0.7.2

package/README.md

@@ -61,8 +61,6 @@ Browse the documentation website at **<https://forgeselect.konexforge.com/docs/>
 - Internationalization (en/vi built in, custom string tables)
 - TypeScript Support (written in strict TypeScript, ships `.d.ts`)
 
-> Planned/in-progress capabilities — Angular/Svelte wrappers — are tracked in the [Roadmap](#roadmap) below and intentionally not listed above as shipped features.
-
 ## Installation
 
 ```bash
@@ -189,8 +187,8 @@ Forge Select is vanilla TypeScript/JavaScript, so it can be mounted inside any f
 - Vanilla JavaScript
 - React — via [`forge-select-react`](./packages/react/README.md) (`ForgeSelectReact` component, controlled `value`/`onChange`)
 - Vue — via [`forge-select-vue`](./packages/vue/README.md) (`ForgeSelectVue` component, `v-model` support)
-- Angular — mount manually for now; a dedicated wrapper is on the [Roadmap](#roadmap)
-- Svelte — mount manually for now; a dedicated wrapper is on the [Roadmap](#roadmap)
+- Angular — mount manually (see [`docs/examples.md`](./docs/examples.md))
+- Svelte — mount manually (see [`docs/examples.md`](./docs/examples.md))
 - Next.js
 - Nuxt
 - Astro
@@ -221,8 +219,6 @@ Run `npm run bench` for a reproducible JSON baseline covering bundle size, initi
 - [x] CSS Variables
 - [x] React Component
 - [x] Vue Component
-- [ ] Angular Component
-- [ ] Svelte Component
 
 ## Plugin Development Guide
 

package/dist/index.cjs

@@ -165,7 +165,7 @@ function renderOptionContent(container, option, template, variant = "row", sanit
 // src/remote.ts
 function buildUrl(ajax, query, page, cursor) {
   if (!ajax.url) throw new Error("ForgeSelect: ajax requires either url or request.");
-  if (typeof ajax.url === "function") return ajax.url(query, page);
+  if (typeof ajax.url === "function") return ajax.url(query, page, cursor);
   if (!ajax.params) return ajax.url;
   const params = new URLSearchParams();
   for (const [key, value] of Object.entries(ajax.params(query, page, cursor))) params.set(key, String(value));
@@ -351,6 +351,12 @@ var ForgeSelect = class {
     this.highlightedIndex = -1;
     this.typeaheadBuffer = "";
     this.typeaheadTimer = null;
+    // Keyed by the option object, not its value: duplicateValuePolicy only warns
+    // by default, so two options can share a value while carrying different
+    // labels, and a value-keyed cache would render the first one's content for
+    // both. Still explicitly bounded — a WeakMap would not collect anything while
+    // `data` holds every key, so scrolling a long list would retain a detached
+    // node per option visited.
     this.rowContentCache = /* @__PURE__ */ new Map();
     this.rowElementCache = /* @__PURE__ */ new Map();
     this.rowHeightCache = /* @__PURE__ */ new Map();
@@ -538,8 +544,21 @@ var ForgeSelect = class {
     this.typeaheadBuffer = "";
     this.highlightedIndex = -1;
     if (this.searchInput) {
+      const hadQuery = this.query !== "";
       this.searchInput.value = "";
       this.query = "";
+      if (hadQuery && this.opts.ajax) {
+        this.ajaxRequestId += 1;
+        if (this.ajaxTimer) {
+          clearTimeout(this.ajaxTimer);
+          this.ajaxTimer = null;
+        }
+        this.ajaxController?.abort();
+        this.ajaxController = null;
+        this.setLoading(false);
+        this.loadingMore = false;
+        this.remoteLoaded = false;
+      }
     }
     this.emitter.emit("close");
     for (const plugin of this.plugins) plugin.onClose?.(this);
@@ -581,9 +600,7 @@ var ForgeSelect = class {
     this.nativeSelect?.removeEventListener("change", this.onNativeChange);
     this.nativeSelect?.removeEventListener("invalid", this.onNativeInvalid);
     this.nativeForm?.removeEventListener("reset", this.onFormReset);
-    this.rowContentCache.clear();
-    this.rowElementCache.clear();
-    this.rowHeightCache.clear();
+    this.clearRowCaches();
     this.searchIndex.clear();
     this.portalHost?.remove();
     this.root.remove();
@@ -675,9 +692,7 @@ var ForgeSelect = class {
     }
     this.root.classList.toggle("forge-select--sortable", this.opts.sortable && this.opts.multiple);
     this.updateSearchVisibility();
-    this.rowContentCache.clear();
-    this.rowElementCache.clear();
-    this.rowHeightCache.clear();
+    this.clearRowCaches();
     this.searchIndex.clear();
     this.renderValue();
     if (this.isOpen) this.renderList();
@@ -761,9 +776,7 @@ var ForgeSelect = class {
       this.afterSelectionChange();
     }
     this.updateSearchVisibility();
-    this.rowContentCache.clear();
-    this.rowElementCache.clear();
-    this.rowHeightCache.clear();
+    this.clearRowCaches();
     this.searchIndex.clear();
     this.highlightedIndex = -1;
     if (this.isOpen) this.renderList();
@@ -904,6 +917,7 @@ var ForgeSelect = class {
     if (portalParent) {
       this.portalHost = document.createElement("div");
       this.portalHost.className = "forge-select forge-select--portal-host";
+      this.portalHost.style.direction = getComputedStyle(this.root).direction;
       this.portalHost.dataset.theme = this.opts.theme;
       this.portalHost.style.setProperty("--fs-item-height", `${this.opts.itemHeight}px`);
       this.portalHost.append(this.dropdown);
@@ -1282,6 +1296,7 @@ var ForgeSelect = class {
         this.announceMaximum(existing);
         return void 0;
       }
+      if (this.opts.beforeSelect?.(existing) === false) return void 0;
       this.selectValue(existing.value, false);
       return { option: existing, created: false };
     }
@@ -1300,6 +1315,7 @@ var ForgeSelect = class {
     const duplicate = this.findOption(option.value);
     if (duplicate) {
       if (this.selected.includes(duplicate.value)) return void 0;
+      if (this.opts.beforeSelect?.(duplicate) === false) return void 0;
       this.selectValue(duplicate.value, false);
       return { option: duplicate, created: false };
     }
@@ -1580,11 +1596,40 @@ var ForgeSelect = class {
   usesVirtualScroll() {
     return this.opts.virtualScroll !== false && this.rows.length > VIRTUAL_THRESHOLD;
   }
+  /**
+   * Drops every per-row cache at once. Rendered content, recycled <li>
+   * elements, and measured heights are all keyed off the current `data`, so
+   * they must be invalidated together whenever `data` is replaced — clearing
+   * only some of them leaves recycled rows carrying state from the old list.
+   */
+  clearRowCaches() {
+    this.rowContentCache.clear();
+    this.rowElementCache.clear();
+    this.rowHeightCache.clear();
+    this.rowOffsetsCache = null;
+  }
+  /** Identifies a row *position*, which is what measured heights are tied to. */
   rowKey(row, index) {
     if (row.kind === "option") return `option:${row.option.value}:${index}`;
     if (row.kind === "group") return `group:${row.label}:${index}`;
     return `${row.kind}:${index}`;
   }
+  /**
+   * Identifies a row's *content* for `<li>` recycling, deliberately without the
+   * row index: filtering shifts every index below the first change, so an
+   * index-keyed element cache misses on every keystroke — exactly when the list
+   * re-renders most. renderRow() rewrites the element completely, so reusing it
+   * at a new position is safe.
+   *
+   * Keys are not guaranteed unique within a render — duplicateValuePolicy
+   * defaults to warning rather than rejecting duplicate values — so callers
+   * must not hand the same element to two rows of one render.
+   */
+  rowElementKey(row) {
+    if (row.kind === "option") return `option:${row.option.value}`;
+    if (row.kind === "group") return `group:${row.label}`;
+    return row.kind;
+  }
   measuredRowHeight(index) {
     return this.opts.variableItemHeight ? this.rowHeightCache.get(this.rowKey(this.rows[index], index)) ?? this.opts.itemHeight : this.opts.itemHeight;
   }
@@ -1646,9 +1691,12 @@ var ForgeSelect = class {
       this.list.append(topSpacer);
     }
     const appended = [];
+    const claimed = /* @__PURE__ */ new Set();
     for (let i = start; i < end; i++) {
-      const key = this.rowKey(this.rows[i], i);
-      const element = this.renderRow(this.rows[i], this.rowElementCache.get(key));
+      const key = this.rowElementKey(this.rows[i]);
+      const cached = this.rowElementCache.get(key);
+      const element = this.renderRow(this.rows[i], cached && !claimed.has(cached) ? cached : void 0);
+      claimed.add(element);
       this.rowElementCache.set(key, element);
       if (this.rowElementCache.size > ROW_CACHE_LIMIT) {
         const oldest = this.rowElementCache.keys().next().value;
@@ -1693,7 +1741,12 @@ var ForgeSelect = class {
       "aria-expanded",
       "aria-level",
       "data-nav-index",
-      "data-option-value"
+      "data-option-value",
+      "data-selection-state",
+      // Tree rows set an inline padding-left indent; clearing the whole
+      // attribute keeps recycling self-contained, so a row reused at a
+      // shallower depth can't inherit the previous row's indent.
+      "style"
     ])
       li.removeAttribute(attribute);
     switch (row.kind) {
@@ -1743,45 +1796,47 @@ var ForgeSelect = class {
         li.textContent = format(this.strings.createOption, { query: this.query.trim() });
         if (row.navIndex === this.highlightedIndex) li.classList.add("forge-select__option--highlighted");
         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, this.isOptionDisabled) === "some") {
-          li.classList.add("forge-select__option--indeterminate");
-          li.dataset.selectionState = "mixed";
-        }
-        if (row.depth > 0) {
-          li.style.paddingLeft = `calc(12px + ${row.depth} * var(--fs-tree-indent, 18px))`;
-        }
-        if (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 {
-          li.id = `${this.uid}-nav-${row.navIndex}`;
-          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));
+      case "option":
+        this.renderOptionRow(li, row);
         break;
-      }
     }
     return li;
   }
+  renderOptionRow(li, row) {
+    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, this.isOptionDisabled) === "some") {
+      li.classList.add("forge-select__option--indeterminate");
+      li.dataset.selectionState = "mixed";
+    }
+    if (row.depth > 0) {
+      li.style.paddingLeft = `calc(12px + ${row.depth} * var(--fs-tree-indent, 18px))`;
+    }
+    if (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 {
+      li.id = `${this.uid}-nav-${row.navIndex}`;
+      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));
+  }
   /**
    * Rendered row content is cached per option value and cloned on each render,
    * so templates run once per option instead of once per scroll frame.
@@ -1811,7 +1866,7 @@ var ForgeSelect = class {
       }
       return holder;
     }
-    let cached = this.rowContentCache.get(option.value);
+    let cached = this.rowContentCache.get(option);
     if (!cached) {
       const holder = document.createElement("span");
       holder.className = "forge-select__option-content";
@@ -1820,7 +1875,7 @@ var ForgeSelect = class {
         const oldest = this.rowContentCache.keys().next().value;
         this.rowContentCache.delete(oldest);
       }
-      this.rowContentCache.set(option.value, holder);
+      this.rowContentCache.set(option, holder);
       cached = holder;
     }
     return cached.cloneNode(true);
@@ -2014,8 +2069,7 @@ var ForgeSelect = class {
         this.data = [...this.data, ...options.filter((o) => !existing.has(o.value))];
       } else {
         this.data = options;
-        this.rowContentCache.clear();
-        this.rowHeightCache.clear();
+        this.clearRowCaches();
       }
       this.page = page;
       this.hasMore = hasMore;
@@ -2028,8 +2082,7 @@ var ForgeSelect = class {
       const error = cause instanceof Error ? cause : new Error(String(cause));
       if (!append) {
         this.data = [];
-        this.rowContentCache.clear();
-        this.rowHeightCache.clear();
+        this.clearRowCaches();
       }
       this.hasMore = false;
       this.loadError = error;