@selkit/dom 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,78 @@
+import { SelkitController, SelkitConfig, SelkitOption } from '@selkit/core';
+
+interface SelkitDomConfig<T = unknown> extends SelkitConfig<T> {
+    /** class 前綴 預設 "selkit" */
+    classPrefix?: string;
+    /** 表單欄位名 設定後自動維護 hidden input 讓傳統表單 submit 帶值 */
+    name?: string;
+    /** 多選時於選項顯示打勾（checkbox 樣式）選項點擊改為 toggle 不隱藏已選 */
+    checkboxes?: boolean;
+    /** 輸入框寬度隨輸入字數增長（以 size 屬性近似）取代預設的 flex 撐滿 */
+    autogrow?: boolean;
+    /** 下拉寬度貼齊內容（至少與控制項同寬 可更寬）而非固定等寬 */
+    dropdownAutoWidth?: boolean;
+    /** 啟用虛擬捲動 大量選項時只渲染可視切片 僅在無分組的扁平清單生效 */
+    virtualScroll?: boolean;
+    /** 虛擬捲動的單列固定高度 px 預設 36 須與實際樣式高度一致 */
+    itemHeight?: number;
+    /** 把下拉浮層掛到指定容器（元素或選擇器）逃離 overflow/transform 祖先的裁切 常用 document.body */
+    dropdownParent?: HTMLElement | string;
+    /** 自訂已選顯示內容（tag 或單值） 回傳字串走 textContent 防 XSS 需 markup（icon 等）請回傳 Node */
+    templateSelection?: (option: SelkitOption<T>, meta: {
+        index: number;
+        multiple: boolean;
+    }) => string | Node;
+    /** 自訂下拉選項內容 回傳字串走 textContent 防 XSS 需 markup（icon 等）請回傳 Node */
+    templateOption?: (option: SelkitOption<T>, meta: {
+        index: number;
+        active: boolean;
+        selected: boolean;
+    }) => string | Node;
+}
+interface SelkitDomInstance<T = unknown> {
+    readonly controller: SelkitController<T>;
+    readonly element: HTMLElement;
+    destroy(): void;
+}
+declare class SelkitDom<T> implements SelkitDomInstance<T> {
+    #private;
+    readonly controller: SelkitController<T>;
+    readonly element: HTMLElement;
+    constructor(target: HTMLElement | string, config: SelkitDomConfig<T>);
+    destroy(): void;
+}
+/** 在指定元素或 selector 對應的元素內建立並掛載一個 Selkit 下拉 */
+declare function createSelkitDom<T = unknown>(host: HTMLElement | string, config?: SelkitDomConfig<T>): SelkitDomInstance<T>;
+
+/**
+ * @selkit/dom — 預設輕量定位器（零依賴）
+ *
+ * 計算邏輯與 DOM 套用分離：computePosition 為純函式（可單元測）
+ * attachPositioner 負責讀取 rect、套 style、監聽 scroll/resize
+ */
+type Placement = 'bottom' | 'top';
+interface Rect {
+    top: number;
+    bottom: number;
+    left: number;
+    width: number;
+}
+interface PositionResult {
+    placement: Placement;
+    top: number;
+    left: number;
+    width: number;
+}
+/**
+ * 依觸發元件位置與下拉高度 決定放上方或下方（空間不足才翻轉）
+ * 並回傳套用座標 不做水平翻轉（select 下拉慣例對齊左緣、同寬）
+ */
+declare function computePosition(triggerRect: Rect, dropdownHeight: number, viewportHeight: number, gap?: number): PositionResult;
+interface Positioner {
+    update(): void;
+    destroy(): void;
+}
+/** 將 dropdown 定位到 trigger 旁 並隨 scroll/resize 更新  */
+declare function attachPositioner(trigger: HTMLElement, dropdown: HTMLElement, autoWidth?: boolean): Positioner;
+
+export { type Placement, type PositionResult, type Positioner, type Rect, SelkitDom as Selkit, SelkitDom, type SelkitDomConfig, type SelkitDomInstance, attachPositioner, computePosition, createSelkitDom, createSelkitDom as sk };

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+import { SelkitController, SelkitConfig, SelkitOption } from '@selkit/core';
+
+interface SelkitDomConfig<T = unknown> extends SelkitConfig<T> {
+    /** class 前綴 預設 "selkit" */
+    classPrefix?: string;
+    /** 表單欄位名 設定後自動維護 hidden input 讓傳統表單 submit 帶值 */
+    name?: string;
+    /** 多選時於選項顯示打勾（checkbox 樣式）選項點擊改為 toggle 不隱藏已選 */
+    checkboxes?: boolean;
+    /** 輸入框寬度隨輸入字數增長（以 size 屬性近似）取代預設的 flex 撐滿 */
+    autogrow?: boolean;
+    /** 下拉寬度貼齊內容（至少與控制項同寬 可更寬）而非固定等寬 */
+    dropdownAutoWidth?: boolean;
+    /** 啟用虛擬捲動 大量選項時只渲染可視切片 僅在無分組的扁平清單生效 */
+    virtualScroll?: boolean;
+    /** 虛擬捲動的單列固定高度 px 預設 36 須與實際樣式高度一致 */
+    itemHeight?: number;
+    /** 把下拉浮層掛到指定容器（元素或選擇器）逃離 overflow/transform 祖先的裁切 常用 document.body */
+    dropdownParent?: HTMLElement | string;
+    /** 自訂已選顯示內容（tag 或單值） 回傳字串走 textContent 防 XSS 需 markup（icon 等）請回傳 Node */
+    templateSelection?: (option: SelkitOption<T>, meta: {
+        index: number;
+        multiple: boolean;
+    }) => string | Node;
+    /** 自訂下拉選項內容 回傳字串走 textContent 防 XSS 需 markup（icon 等）請回傳 Node */
+    templateOption?: (option: SelkitOption<T>, meta: {
+        index: number;
+        active: boolean;
+        selected: boolean;
+    }) => string | Node;
+}
+interface SelkitDomInstance<T = unknown> {
+    readonly controller: SelkitController<T>;
+    readonly element: HTMLElement;
+    destroy(): void;
+}
+declare class SelkitDom<T> implements SelkitDomInstance<T> {
+    #private;
+    readonly controller: SelkitController<T>;
+    readonly element: HTMLElement;
+    constructor(target: HTMLElement | string, config: SelkitDomConfig<T>);
+    destroy(): void;
+}
+/** 在指定元素或 selector 對應的元素內建立並掛載一個 Selkit 下拉 */
+declare function createSelkitDom<T = unknown>(host: HTMLElement | string, config?: SelkitDomConfig<T>): SelkitDomInstance<T>;
+
+/**
+ * @selkit/dom — 預設輕量定位器（零依賴）
+ *
+ * 計算邏輯與 DOM 套用分離：computePosition 為純函式（可單元測）
+ * attachPositioner 負責讀取 rect、套 style、監聽 scroll/resize
+ */
+type Placement = 'bottom' | 'top';
+interface Rect {
+    top: number;
+    bottom: number;
+    left: number;
+    width: number;
+}
+interface PositionResult {
+    placement: Placement;
+    top: number;
+    left: number;
+    width: number;
+}
+/**
+ * 依觸發元件位置與下拉高度 決定放上方或下方（空間不足才翻轉）
+ * 並回傳套用座標 不做水平翻轉（select 下拉慣例對齊左緣、同寬）
+ */
+declare function computePosition(triggerRect: Rect, dropdownHeight: number, viewportHeight: number, gap?: number): PositionResult;
+interface Positioner {
+    update(): void;
+    destroy(): void;
+}
+/** 將 dropdown 定位到 trigger 旁 並隨 scroll/resize 更新  */
+declare function attachPositioner(trigger: HTMLElement, dropdown: HTMLElement, autoWidth?: boolean): Positioner;
+
+export { type Placement, type PositionResult, type Positioner, type Rect, SelkitDom as Selkit, SelkitDom, type SelkitDomConfig, type SelkitDomInstance, attachPositioner, computePosition, createSelkitDom, createSelkitDom as sk };