@selkit/dom 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -72,6 +72,7 @@ function attachPositioner(trigger, dropdown, autoWidth = false) {
 // src/dom.ts
 var LOAD_MORE_THRESHOLD = 32;
 var DEFAULT_ITEM_HEIGHT = 36;
+var DEFAULT_GROUP_HEIGHT = 28;
 var SR_ONLY_CSS = "position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0";
 function resolveParent(parent) {
   if (!parent) return null;
@@ -152,6 +153,7 @@ var SelkitDom = class {
   #name;
   #virtual;
   #itemHeight;
+  #groupHeight;
   #dropdownParent;
   #templateSelection;
   #templateOption;
@@ -170,6 +172,8 @@ var SelkitDom = class {
   #hiddenContainer = null;
   #selectPrevDisplay = "";
   #dragFrom = -1;
+  /** 上次已捲入可視的 activeIndex 僅在變動時才捲 避免跟使用者手動捲動打架 */
+  #lastActive = -1;
   #positioner = null;
   #unsubscribe;
   #offClose;
@@ -194,6 +198,7 @@ var SelkitDom = class {
     this.#name = cfg.name;
     this.#virtual = cfg.virtualScroll ?? false;
     this.#itemHeight = cfg.itemHeight ?? DEFAULT_ITEM_HEIGHT;
+    this.#groupHeight = cfg.groupHeight ?? DEFAULT_GROUP_HEIGHT;
     this.#dropdownParent = resolveParent(cfg.dropdownParent);
     this.#templateSelection = cfg.templateSelection;
     this.#templateOption = cfg.templateOption;
@@ -442,6 +447,54 @@ var SelkitDom = class {
     this.#syncForm();
     this.element.classList.toggle(this.#cls("", "open"), s.isOpen);
     this.element.classList.toggle(this.#cls("", "disabled"), s.disabled);
+    this.#scrollActiveIntoView(s);
+  }
+  /**
+   * 鍵盤導航/開啟時讓作用中選項保持可見（aria-activedescendant 完整度）
+   * 僅在 activeIndex 變動時動作 手動捲動觸發的重繪不會跟著捲
+   */
+  #scrollActiveIntoView(s) {
+    if (!s.isOpen) {
+      this.#lastActive = -1;
+      return;
+    }
+    if (s.activeIndex === this.#lastActive || s.activeIndex < 0) return;
+    this.#lastActive = s.activeIndex;
+    const rows = this.controller.getGroupedView().rows;
+    const hasGroups = rows.some((r) => r.type === "group");
+    if (this.#virtual && !hasGroups) {
+      const next = (0, import_core.computeScrollIntoView)({
+        index: s.activeIndex,
+        scrollTop: this.#dropdown.scrollTop,
+        viewportHeight: this.#dropdown.clientHeight,
+        itemHeight: this.#itemHeight
+      });
+      if (next !== null) {
+        this.#dropdown.scrollTop = next;
+        this.#renderOptions(s);
+      }
+      return;
+    }
+    if (this.#virtual && hasGroups) {
+      const rowIndex = rows.findIndex(
+        (r) => r.type !== "group" && r.index === s.activeIndex
+      );
+      const next = (0, import_core.computeScrollIntoViewVariable)({
+        heights: this.#rowHeights(rows),
+        rowIndex,
+        scrollTop: this.#dropdown.scrollTop,
+        viewportHeight: this.#dropdown.clientHeight
+      });
+      if (next !== null) {
+        this.#dropdown.scrollTop = next;
+        this.#renderOptions(s);
+      }
+      return;
+    }
+    const active = this.#dropdown.querySelector(
+      `.${this.#cls("option", "active")}`
+    );
+    active?.scrollIntoView?.({ block: "nearest" });
   }
   /** 套用模板輸出：字串走 textContent（防 XSS）Node 直接掛入 */
   #applyTemplate(host, out) {
@@ -555,40 +608,61 @@ var SelkitDom = class {
         itemHeight: this.#itemHeight,
         itemCount: view.rows.length
       });
-      this.#dropdown.append(this.#spacer(range.paddingTop));
-      for (let i = range.startIndex; i < range.endIndex; i++) {
-        const row = view.rows[i];
-        if (row?.type === "option") {
-          this.#dropdown.append(this.#buildOption(row, a11y, s.activeIndex));
-        } else if (row?.type === "create") {
-          this.#dropdown.append(this.#buildCreateRow(row, a11y, s.activeIndex));
-        }
-      }
-      this.#dropdown.append(this.#spacer(range.paddingBottom));
+      this.#renderVirtualSlice(view.rows, range, a11y, s.activeIndex);
       return;
     }
-    for (const row of view.rows) {
-      if (row.type === "group") {
-        const group = document.createElement("div");
-        group.className = this.#cls("group");
-        if (row.disabled) group.classList.add(this.#cls("group", "disabled"));
-        if (this.#templateGroup) {
-          this.#applyTemplate(
-            group,
-            this.#templateGroup({ label: row.label, disabled: !!row.disabled })
-          );
-        } else {
-          group.textContent = row.label;
-        }
-        this.#dropdown.append(group);
-        continue;
-      }
-      if (row.type === "create") {
-        this.#dropdown.append(this.#buildCreateRow(row, a11y, s.activeIndex));
-        continue;
-      }
-      this.#dropdown.append(this.#buildOption(row, a11y, s.activeIndex));
+    if (this.#virtual && hasGroups) {
+      const win = (0, import_core.computeVirtualWindow)({
+        heights: this.#rowHeights(view.rows),
+        scrollTop: this.#dropdown.scrollTop,
+        viewportHeight: this.#dropdown.clientHeight
+      });
+      this.#renderVirtualSlice(view.rows, win, a11y, s.activeIndex);
+      return;
+    }
+    for (const row of view.rows) this.#renderRow(row, a11y, s.activeIndex);
+  }
+  /** 每列高度：分組標題用 groupHeight 其餘（option/create）用 itemHeight */
+  #rowHeights(rows) {
+    return rows.map(
+      (r) => r.type === "group" ? this.#groupHeight : this.#itemHeight
+    );
+  }
+  /** 渲染虛擬切片：上下佔位 + range 內各列 共用扁平與分組兩路徑 */
+  #renderVirtualSlice(rows, range, a11y, activeIndex) {
+    this.#dropdown.append(this.#spacer(range.paddingTop));
+    for (let i = range.startIndex; i < range.endIndex; i++) {
+      const row = rows[i];
+      if (row) this.#renderRow(row, a11y, activeIndex);
+    }
+    this.#dropdown.append(this.#spacer(range.paddingBottom));
+  }
+  /** 依列型別渲染並掛入下拉 group / create / option */
+  #renderRow(row, a11y, activeIndex) {
+    if (row.type === "group") {
+      this.#dropdown.append(this.#buildGroupRow(row));
+      return;
+    }
+    if (row.type === "create") {
+      this.#dropdown.append(this.#buildCreateRow(row, a11y, activeIndex));
+      return;
+    }
+    this.#dropdown.append(this.#buildOption(row, a11y, activeIndex));
+  }
+  /** 分組標題列 套用 templateGroup（無則用 label）*/
+  #buildGroupRow(row) {
+    const group = document.createElement("div");
+    group.className = this.#cls("group");
+    if (row.disabled) group.classList.add(this.#cls("group", "disabled"));
+    if (this.#templateGroup) {
+      this.#applyTemplate(
+        group,
+        this.#templateGroup({ label: row.label, disabled: !!row.disabled })
+      );
+    } else {
+      group.textContent = row.label;
     }
+    return group;
   }
   /** 「建立新項」列 共用 option 樣式與 a11y 但點擊走 createTag */
   #buildCreateRow(row, a11y, activeIndex) {

package/dist/index.d.cts

@@ -15,6 +15,8 @@ interface SelkitDomConfig<T = unknown> extends SelkitConfig<T> {
     virtualScroll?: boolean;
     /** 虛擬捲動的單列固定高度 px 預設 36 須與實際樣式高度一致 */
     itemHeight?: number;
+    /** 虛擬捲動下分組標題列的固定高度 px 預設 28 須與實際樣式高度一致 */
+    groupHeight?: number;
     /** 把下拉浮層掛到指定容器（元素或選擇器）逃離 overflow/transform 祖先的裁切 常用 document.body */
     dropdownParent?: HTMLElement | string;
     /** 自訂已選顯示內容（tag 或單值） 回傳字串走 textContent 防 XSS 需 markup（icon 等）請回傳 Node */

package/dist/index.d.ts

@@ -15,6 +15,8 @@ interface SelkitDomConfig<T = unknown> extends SelkitConfig<T> {
     virtualScroll?: boolean;
     /** 虛擬捲動的單列固定高度 px 預設 36 須與實際樣式高度一致 */
     itemHeight?: number;
+    /** 虛擬捲動下分組標題列的固定高度 px 預設 28 須與實際樣式高度一致 */
+    groupHeight?: number;
     /** 把下拉浮層掛到指定容器（元素或選擇器）逃離 overflow/transform 祖先的裁切 常用 document.body */
     dropdownParent?: HTMLElement | string;
     /** 自訂已選顯示內容（tag 或單值） 回傳字串走 textContent 防 XSS 需 markup（icon 等）請回傳 Node */

package/dist/index.js

@@ -1,5 +1,11 @@
 // src/dom.ts
-import { computeVirtualRange, createSelkit } from "@selkit/core";
+import {
+  computeScrollIntoView,
+  computeScrollIntoViewVariable,
+  computeVirtualRange,
+  computeVirtualWindow,
+  createSelkit
+} from "@selkit/core";
 
 // src/positioner.ts
 function computePosition(triggerRect, dropdownHeight, viewportHeight, gap = 4) {
@@ -41,6 +47,7 @@ function attachPositioner(trigger, dropdown, autoWidth = false) {
 // src/dom.ts
 var LOAD_MORE_THRESHOLD = 32;
 var DEFAULT_ITEM_HEIGHT = 36;
+var DEFAULT_GROUP_HEIGHT = 28;
 var SR_ONLY_CSS = "position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0";
 function resolveParent(parent) {
   if (!parent) return null;
@@ -121,6 +128,7 @@ var SelkitDom = class {
   #name;
   #virtual;
   #itemHeight;
+  #groupHeight;
   #dropdownParent;
   #templateSelection;
   #templateOption;
@@ -139,6 +147,8 @@ var SelkitDom = class {
   #hiddenContainer = null;
   #selectPrevDisplay = "";
   #dragFrom = -1;
+  /** 上次已捲入可視的 activeIndex 僅在變動時才捲 避免跟使用者手動捲動打架 */
+  #lastActive = -1;
   #positioner = null;
   #unsubscribe;
   #offClose;
@@ -163,6 +173,7 @@ var SelkitDom = class {
     this.#name = cfg.name;
     this.#virtual = cfg.virtualScroll ?? false;
     this.#itemHeight = cfg.itemHeight ?? DEFAULT_ITEM_HEIGHT;
+    this.#groupHeight = cfg.groupHeight ?? DEFAULT_GROUP_HEIGHT;
     this.#dropdownParent = resolveParent(cfg.dropdownParent);
     this.#templateSelection = cfg.templateSelection;
     this.#templateOption = cfg.templateOption;
@@ -411,6 +422,54 @@ var SelkitDom = class {
     this.#syncForm();
     this.element.classList.toggle(this.#cls("", "open"), s.isOpen);
     this.element.classList.toggle(this.#cls("", "disabled"), s.disabled);
+    this.#scrollActiveIntoView(s);
+  }
+  /**
+   * 鍵盤導航/開啟時讓作用中選項保持可見（aria-activedescendant 完整度）
+   * 僅在 activeIndex 變動時動作 手動捲動觸發的重繪不會跟著捲
+   */
+  #scrollActiveIntoView(s) {
+    if (!s.isOpen) {
+      this.#lastActive = -1;
+      return;
+    }
+    if (s.activeIndex === this.#lastActive || s.activeIndex < 0) return;
+    this.#lastActive = s.activeIndex;
+    const rows = this.controller.getGroupedView().rows;
+    const hasGroups = rows.some((r) => r.type === "group");
+    if (this.#virtual && !hasGroups) {
+      const next = computeScrollIntoView({
+        index: s.activeIndex,
+        scrollTop: this.#dropdown.scrollTop,
+        viewportHeight: this.#dropdown.clientHeight,
+        itemHeight: this.#itemHeight
+      });
+      if (next !== null) {
+        this.#dropdown.scrollTop = next;
+        this.#renderOptions(s);
+      }
+      return;
+    }
+    if (this.#virtual && hasGroups) {
+      const rowIndex = rows.findIndex(
+        (r) => r.type !== "group" && r.index === s.activeIndex
+      );
+      const next = computeScrollIntoViewVariable({
+        heights: this.#rowHeights(rows),
+        rowIndex,
+        scrollTop: this.#dropdown.scrollTop,
+        viewportHeight: this.#dropdown.clientHeight
+      });
+      if (next !== null) {
+        this.#dropdown.scrollTop = next;
+        this.#renderOptions(s);
+      }
+      return;
+    }
+    const active = this.#dropdown.querySelector(
+      `.${this.#cls("option", "active")}`
+    );
+    active?.scrollIntoView?.({ block: "nearest" });
   }
   /** 套用模板輸出：字串走 textContent（防 XSS）Node 直接掛入 */
   #applyTemplate(host, out) {
@@ -524,40 +583,61 @@ var SelkitDom = class {
         itemHeight: this.#itemHeight,
         itemCount: view.rows.length
       });
-      this.#dropdown.append(this.#spacer(range.paddingTop));
-      for (let i = range.startIndex; i < range.endIndex; i++) {
-        const row = view.rows[i];
-        if (row?.type === "option") {
-          this.#dropdown.append(this.#buildOption(row, a11y, s.activeIndex));
-        } else if (row?.type === "create") {
-          this.#dropdown.append(this.#buildCreateRow(row, a11y, s.activeIndex));
-        }
-      }
-      this.#dropdown.append(this.#spacer(range.paddingBottom));
+      this.#renderVirtualSlice(view.rows, range, a11y, s.activeIndex);
       return;
     }
-    for (const row of view.rows) {
-      if (row.type === "group") {
-        const group = document.createElement("div");
-        group.className = this.#cls("group");
-        if (row.disabled) group.classList.add(this.#cls("group", "disabled"));
-        if (this.#templateGroup) {
-          this.#applyTemplate(
-            group,
-            this.#templateGroup({ label: row.label, disabled: !!row.disabled })
-          );
-        } else {
-          group.textContent = row.label;
-        }
-        this.#dropdown.append(group);
-        continue;
-      }
-      if (row.type === "create") {
-        this.#dropdown.append(this.#buildCreateRow(row, a11y, s.activeIndex));
-        continue;
-      }
-      this.#dropdown.append(this.#buildOption(row, a11y, s.activeIndex));
+    if (this.#virtual && hasGroups) {
+      const win = computeVirtualWindow({
+        heights: this.#rowHeights(view.rows),
+        scrollTop: this.#dropdown.scrollTop,
+        viewportHeight: this.#dropdown.clientHeight
+      });
+      this.#renderVirtualSlice(view.rows, win, a11y, s.activeIndex);
+      return;
+    }
+    for (const row of view.rows) this.#renderRow(row, a11y, s.activeIndex);
+  }
+  /** 每列高度：分組標題用 groupHeight 其餘（option/create）用 itemHeight */
+  #rowHeights(rows) {
+    return rows.map(
+      (r) => r.type === "group" ? this.#groupHeight : this.#itemHeight
+    );
+  }
+  /** 渲染虛擬切片：上下佔位 + range 內各列 共用扁平與分組兩路徑 */
+  #renderVirtualSlice(rows, range, a11y, activeIndex) {
+    this.#dropdown.append(this.#spacer(range.paddingTop));
+    for (let i = range.startIndex; i < range.endIndex; i++) {
+      const row = rows[i];
+      if (row) this.#renderRow(row, a11y, activeIndex);
+    }
+    this.#dropdown.append(this.#spacer(range.paddingBottom));
+  }
+  /** 依列型別渲染並掛入下拉 group / create / option */
+  #renderRow(row, a11y, activeIndex) {
+    if (row.type === "group") {
+      this.#dropdown.append(this.#buildGroupRow(row));
+      return;
+    }
+    if (row.type === "create") {
+      this.#dropdown.append(this.#buildCreateRow(row, a11y, activeIndex));
+      return;
+    }
+    this.#dropdown.append(this.#buildOption(row, a11y, activeIndex));
+  }
+  /** 分組標題列 套用 templateGroup（無則用 label）*/
+  #buildGroupRow(row) {
+    const group = document.createElement("div");
+    group.className = this.#cls("group");
+    if (row.disabled) group.classList.add(this.#cls("group", "disabled"));
+    if (this.#templateGroup) {
+      this.#applyTemplate(
+        group,
+        this.#templateGroup({ label: row.label, disabled: !!row.disabled })
+      );
+    } else {
+      group.textContent = row.label;
     }
+    return group;
   }
   /** 「建立新項」列 共用 option 樣式與 a11y 但點擊走 createTag */
   #buildCreateRow(row, a11y, activeIndex) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selkit/dom",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Vanilla JS renderer for Selkit — DOM, events, a11y and default positioner.",
   "license": "MIT",
   "type": "module",
@@ -19,7 +19,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@selkit/core": "0.2.0"
+    "@selkit/core": "0.4.0"
   },
   "devDependencies": {
     "axe-core": "^4.12.1",