@icen.ai/ui 0.9.0 → 0.10.0

package/dist/behaviors/mentions.d.mts

@@ -0,0 +1,93 @@
+import { SuggestionSourceContext } from './suggestions.js';
+
+/** Mention input with object-level mention entities. createMentions accepts a
+ * host containing a native `<textarea class="icen-input">` (declarative markup
+ * stays unchanged) and replaces it with a rich editor
+ * `div.icen-input.icen-mentions-editor` (contenteditable, role=textbox,
+ * aria-multiline). Directory and custom mentions render as atomic
+ * `<span class="icen-mention-token is-directory|is-custom" contenteditable="false">`
+ * pills: the caret can never enter a token, Backspace/Delete remove the whole
+ * token, and the model behind every token keeps the complete source object
+ * (getValue()/getMentions() return entity blocks, never regex guesses). The
+ * `@query` trigger/caret queries share cancellable source ownership with
+ * autocomplete; the portal panel keeps its named listbox plus sibling
+ * loading/empty/retry states, and multi-line textbox semantics intentionally
+ * omit aria-expanded. Render-only text is always written via textContent.
+ *
+ * 模式（opts.mode）：'select'（默认）只能从 source 候选中选择；'custom' 允许把
+ * 当前 query 创建为自定义提及（createCustom 可返回完整自定义对象，默认
+ * `{ id: 'custom:'+query, label: query }`，token 虚线边 + 「自定义」徽标）。
+ */
+
+/** 一条提及候选/数据对象：id 必填，展示名取 label ?? name ?? id；额外字段（email/role…）全量保留。 */
+type MentionItem<T = Record<string, unknown>> = {
+    /** 业务唯一键（随 MentionEntity 与 icen:mention-select 回给宿主） */
+    id: string;
+    /** 展示名（优先于 name/id） */
+    label?: string;
+    /** 展示名（label 缺省时回退） */
+    name?: string;
+    /** 辅助匹配关键字（给 source 过滤用，组件不消费） */
+    keywords?: string;
+    /** true = 置灰不可选（键盘导航跳过，点击不生效） */
+    disabled?: boolean;
+} & T;
+/** 一个仍存活于编辑区中的提及实体：item 是完整原始 user/custom 对象。 */
+interface MentionEntity<T = Record<string, unknown>> {
+    type: 'mention';
+    id: string;
+    /** 展示名（label ?? name ?? id 推导后的最终值） */
+    label: string;
+    /** directory = 来自 source 候选；custom = 自定义创建的提及 */
+    kind: 'directory' | 'custom';
+    /** 完整源对象（目录成员保留完整 user 对象；自定义保留完整自定义对象） */
+    item: MentionItem<T>;
+}
+/** 内容块：纯文本段或原子提及段（getValue() 的返回单元）。 */
+type MentionValue<T = Record<string, unknown>> = {
+    type: 'text';
+    text: string;
+} | MentionEntity<T>;
+interface MentionsOptions<T = Record<string, unknown>> {
+    /** 查询过滤源：按 query 返回候选（同步数组或 Promise）；返回值可携带任意额外字段，全量保留进实体 */
+    source: (query: string, context: SuggestionSourceContext) => MentionItem<T>[] | Promise<MentionItem<T>[]>;
+    /** 触发字符（默认 '@'） */
+    trigger?: string;
+    /** 选择模式：'select'（默认）只能从候选中选；'custom' 允许把当前 query 创建成自定义提及 */
+    mode?: 'select' | 'custom';
+    /** custom 模式：宿主返回完整自定义对象（缺省 `{ id: 'custom:'+query, label: query }`） */
+    createCustom?: (query: string) => MentionItem<T>;
+    /** 面板最多显示条数（默认 8；不含追加的「创建 …」项） */
+    max?: number;
+    /** 触发所需最少查询字符数（默认 0 = 输入 @ 即出） */
+    minChars?: number;
+    /** source 调用防抖（默认 160ms；0 = 同步立即调） */
+    debounceMs?: number;
+    /** 异步加载态占位文案（默认取 i18n mentions.loading，可被 opts 覆盖） */
+    loadingLabel?: string;
+    errorLabel?: string;
+    retryLabel?: string;
+    noResultsLabel?: string;
+    renderItem?: (item: MentionItem<T>, query: string) => Node | string;
+    /** 内容变化（在 icen:mention-change 派发后调用） */
+    onChange?: (value: MentionValue<T>[], text: string) => void;
+    /** 选中回调（在 icen:mention-select 派发后调用；item 是完整 MentionEntity） */
+    onSelect?: (entity: MentionEntity<T>) => void;
+}
+interface MentionsHandle<T = Record<string, unknown>> {
+    /** 内容块视图：text/mention 交替；mention 块携带完整源对象 */
+    getValue(): MentionValue<T>[];
+    /** 纯文本视图（token 展开为 `@label`） */
+    getText(): string;
+    /** 当前仍存在的提及实体（只含存活 token） */
+    getMentions(): MentionEntity<T>[];
+    /** 程序化设值：纯文本字符串，或 string | MentionValue | 原始对象 的混合数组（有 id 的对象渲染成原子提及） */
+    setValue(value: string | Array<string | MentionValue<T> | MentionItem<T>>): void;
+    /** Cancel the current suggestions without modifying the text. */
+    close(): void;
+    /** 关闭面板、摘除监听/计时器，恢复原始 textarea 并回填当前纯文本 */
+    destroy(): void;
+}
+declare function createMentions<T = Record<string, unknown>>(el: HTMLElement, opts: MentionsOptions<T>): MentionsHandle<T>;
+
+export { type MentionEntity, type MentionItem, type MentionValue, type MentionsHandle, type MentionsOptions, createMentions };