@icen.ai/ui 0.9.0 → 0.10.0

package/dist/behaviors/autocomplete.d.mts

@@ -0,0 +1,53 @@
+import { SuggestionSourceContext } from './suggestions.js';
+
+/** Single-line combobox suggestions. A named listbox contains options only;
+ * loading, empty and retry states are siblings. Sources receive AbortSignal,
+ * replacement queries invalidate immediately (including debounce), and close /
+ * blur / value replacement / destroy cancel every old continuation. IME editing
+ * stays native; strict and freeSolo commits preserve the existing value API.
+ */
+
+/** 候选项：裸字符串或 { value, label } 对（value 是提交值，label 是展示名）。 */
+type AutocompleteItem = string | {
+    value: string;
+    label: string;
+};
+/** 归一后的候选项（renderItem 收到的也是这个形态）。 */
+interface AutocompleteOption {
+    value: string;
+    label: string;
+}
+interface AutocompleteOptions {
+    /** 查询过滤源：按 query 返回候选（同步数组或 Promise） */
+    source: (query: string, context: SuggestionSourceContext) => AutocompleteItem[] | Promise<AutocompleteItem[]>;
+    /** 触发查询的最少字符数（默认 1） */
+    minChars?: number;
+    /** source 调用防抖（默认 160ms；0 = 同步立即调） */
+    debounceMs?: number;
+    /** 面板最多显示条数（默认 8） */
+    maxItems?: number;
+    /** true = 允许不在清单的任意输入（失焦落定，只派 change）；false（默认）= 失焦无选中回退原值 */
+    freeSolo?: boolean;
+    /** 自定义选项渲染：Node 直接挂载 / string 走 textContent（此时不做 <mark> 高亮） */
+    renderItem?: (item: AutocompleteOption, query: string) => Node | string;
+    /** 空结果态文案（默认取 i18n autocomplete.empty，可被 opts 覆盖） */
+    noResultsLabel?: string;
+    loadingLabel?: string;
+    errorLabel?: string;
+    retryLabel?: string;
+}
+interface AutocompleteHandle {
+    /** 最近提交值（选中值 / freeSolo 落定值 / 初始值） */
+    getValue(): string;
+    /** 设置值（同时更新显示值；不派事件、不开层） */
+    setValue(v: string): void;
+    /** 程序化开层（按当前输入值拉取并渲染，不受 minChars 限制） */
+    open(): void;
+    /** 关层（不动显示值） */
+    close(): void;
+    /** 摘除全部监听/计时器/面板，还原 input role/aria 属性 */
+    destroy(): void;
+}
+declare function createAutocomplete(input: HTMLInputElement, opts: AutocompleteOptions): AutocompleteHandle;
+
+export { type AutocompleteHandle, type AutocompleteItem, type AutocompleteOption, type AutocompleteOptions, createAutocomplete };