@ai-group/chat-sdk 3.7.1-alpha1 → 3.7.1-alpha10

package/dist/esm/components/XAdkSender/InlineTagInput.js

@@ -1,15 +1,20 @@
+import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
 import _toConsumableArray from "@babel/runtime/helpers/esm/toConsumableArray";
-import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useRef } from "react";
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import React, { forwardRef, useCallback, useEffect, useLayoutEffect, useImperativeHandle, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
 import { useStyles } from "./styles";
+import { parseMarkdownResourceLinksAsParts } from "../../utils/markdownResource";
 import { Fragment as _Fragment } from "react/jsx-runtime";
 import { jsx as _jsx } from "react/jsx-runtime";
-var TAG_ATTR = "data-xadk-inline-tag-id";
-// contenteditable 无法把光标放进 contenteditable=false 的标签里，需用零宽字符承接“标签后方”的光标。
+import { jsxs as _jsxs } from "react/jsx-runtime";
+var MENTION_ATTR = "data-xadk-inline-mention-id";
+// contenteditable 无法把光标放进 contenteditable=false 的 Mention 里，需用零宽字符承接“Mention 后方”的光标。
 var CARET_TEXT = "\u200B";
 var createTextNode = function createTextNode(text) {
   return document.createTextNode(text);
 };
+var useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 var normalizeText = function normalizeText(text) {
   return text.replace(/\u200B/g, "").replace(/\u00a0/g, " ");
 };
@@ -25,33 +30,52 @@ var toRawOffset = function toRawOffset(text, plainOffset) {
   }
   return text.length;
 };
+
+// 内联标签展示逻辑
 var InlineTagInput = /*#__PURE__*/forwardRef(function (_ref, ref) {
   var value = _ref.value,
-    tags = _ref.tags,
+    mentions = _ref.mentions,
+    defaultInputParts = _ref.defaultInputParts,
     placeholder = _ref.placeholder,
     disabled = _ref.disabled,
     onChange = _ref.onChange,
-    onTagsChange = _ref.onTagsChange,
+    onMentionsChange = _ref.onMentionsChange,
     onKeyDown = _ref.onKeyDown,
-    onKeyUp = _ref.onKeyUp,
-    renderTag = _ref.renderTag;
+    _onKeyUp = _ref.onKeyUp,
+    renderMention = _ref.renderMention;
   var styles = useStyles();
   var editorRef = useRef(null);
-  var latestTagsRef = useRef(tags);
+  var latestMentionsRef = useRef(mentions);
   var tagRootMapRef = useRef(new WeakMap());
   var composingRef = useRef(false);
   var lastInsertedCaretRef = useRef(null);
+  var savedRangeRef = useRef(null);
+  var defaultInputPartsAppliedRef = useRef(false);
+  var skipEmptyCleanupOnceRef = useRef(false);
+  var structuralCleanupFrameRef = useRef(null);
+  var _useState = useState(function () {
+      return Boolean(value || mentions.length);
+    }),
+    _useState2 = _slicedToArray(_useState, 2),
+    hasContent = _useState2[0],
+    setHasContent = _useState2[1];
+  var lastEmittedStateRef = useRef({
+    value: value,
+    mentionIds: mentions.map(function (mention) {
+      return mention.id;
+    }).join("|")
+  });
   useEffect(function () {
-    latestTagsRef.current = tags;
-  }, [tags]);
-  var getOrderedTags = useCallback(function () {
+    latestMentionsRef.current = mentions;
+  }, [mentions]);
+  var getOrderedMentions = useCallback(function () {
     var editor = editorRef.current;
     if (!editor) return [];
-    var tagMap = new Map(latestTagsRef.current.map(function (tag) {
-      return [tag.id, tag];
+    var mentionMap = new Map(latestMentionsRef.current.map(function (mention) {
+      return [mention.id, mention];
     }));
-    return Array.from(editor.querySelectorAll("[".concat(TAG_ATTR, "]"))).map(function (node) {
-      return tagMap.get(node.dataset.xadkInlineTagId || "");
+    return Array.from(editor.querySelectorAll("[".concat(MENTION_ATTR, "]"))).map(function (node) {
+      return mentionMap.get(node.dataset.xadkInlineMentionId || "");
     }).filter(Boolean);
   }, []);
 
@@ -67,23 +91,61 @@ var InlineTagInput = /*#__PURE__*/forwardRef(function (_ref, ref) {
     });
     return normalizeText(text);
   }, []);
+
+  // 提交时需要保留文本与 Mention 的真实顺序；仅靠 value + mentions 无法区分 Mention 在句首、句中还是句尾。
+  var getParts = useCallback(function () {
+    var editor = editorRef.current;
+    if (!editor) return [];
+    var mentionMap = new Map(latestMentionsRef.current.map(function (mention) {
+      return [mention.id, mention];
+    }));
+    var parts = [];
+    editor.childNodes.forEach(function (node) {
+      if (node.nodeType === Node.TEXT_NODE) {
+        var text = normalizeText(node.textContent || "");
+        if (text) parts.push({
+          type: "text",
+          text: text
+        });
+        return;
+      }
+      if (node instanceof HTMLElement && node.hasAttribute(MENTION_ATTR)) {
+        var mentionId = node.dataset.xadkInlineMentionId || "";
+        var _mention = mentionMap.get(mentionId);
+        if (_mention) parts.push({
+          type: "mention",
+          mention: _mention
+        });
+      }
+    });
+    return parts;
+  }, []);
   var emitChange = useCallback(function () {
-    onChange(getPlainText());
-    onTagsChange(getOrderedTags());
-  }, [getOrderedTags, getPlainText, onChange, onTagsChange]);
+    var nextValue = getPlainText();
+    var nextMentions = getOrderedMentions();
+    setHasContent(Boolean(nextValue || nextMentions.length));
+    lastEmittedStateRef.current = {
+      value: nextValue,
+      mentionIds: nextMentions.map(function (mention) {
+        return mention.id;
+      }).join("|")
+    };
+    onChange(nextValue);
+    onMentionsChange(nextMentions);
+  }, [getOrderedMentions, getPlainText, onChange, onMentionsChange]);
   var removeTextRange = useCallback(function (node, start, end) {
     var text = node.textContent || "";
     node.textContent = "".concat(text.slice(0, start)).concat(text.slice(end));
     if (!node.textContent) node.remove();
   }, []);
-  var removeTagNode = useCallback(function (node) {
+  var removeMentionNode = useCallback(function (node) {
     var _tagRootMapRef$curren;
     var previous = node.previousSibling;
     var next = node.nextSibling;
     (_tagRootMapRef$curren = tagRootMapRef.current.get(node)) === null || _tagRootMapRef$curren === void 0 || _tagRootMapRef$curren.unmount();
     node.remove();
 
-    // 标签后会补一个不可见光标锚点；删除标签时同步清理，避免留下冗余节点。
+    // Mention 后会补一个不可见光标锚点；删除 Mention 时同步清理，避免留下冗余节点。
     if ((next === null || next === void 0 ? void 0 : next.nodeType) === Node.TEXT_NODE) {
       var _text$match;
       var text = next.textContent || "";
@@ -102,51 +164,69 @@ var InlineTagInput = /*#__PURE__*/forwardRef(function (_ref, ref) {
       }
     }
   }, [removeTextRange]);
-  var removeTagById = useCallback(function (id) {
+  var removeMentionById = useCallback(function (id) {
     var editor = editorRef.current;
-    var node = Array.from((editor === null || editor === void 0 ? void 0 : editor.querySelectorAll("[".concat(TAG_ATTR, "]"))) || []).find(function (item) {
-      return item.dataset.xadkInlineTagId === id;
+    var node = Array.from((editor === null || editor === void 0 ? void 0 : editor.querySelectorAll("[".concat(MENTION_ATTR, "]"))) || []).find(function (item) {
+      return item.dataset.xadkInlineMentionId === id;
     });
     if (node) {
-      removeTagNode(node);
+      removeMentionNode(node);
     }
     emitChange();
     editor === null || editor === void 0 || editor.focus();
-  }, [emitChange, removeTagNode]);
+  }, [emitChange, removeMentionNode]);
 
-  // 标签节点本身不可编辑；删除入口通过 onRemove 回到组件内部统一维护 DOM 与 tags。
-  var buildTagNode = useCallback(function (tag) {
+  // Mention 节点本身不可编辑；删除入口通过 onRemove 回到组件内部统一维护 DOM 与 mentions。
+  var buildMentionNode = useCallback(function (mention) {
     var span = document.createElement("span");
     span.setAttribute("contenteditable", "false");
-    span.setAttribute(TAG_ATTR, tag.id);
-    span.dataset.xadkInlineTagId = tag.id;
+    span.setAttribute(MENTION_ATTR, mention.id);
+    span.dataset.xadkInlineMentionId = mention.id;
+    span.dataset.xadkInlineMentionType = mention.type;
     span.className = styles.inlineTag;
-    if (renderTag) {
+    if (renderMention) {
       var root = createRoot(span);
       tagRootMapRef.current.set(span, root);
       root.render( /*#__PURE__*/_jsx(_Fragment, {
-        children: renderTag(tag, {
+        children: renderMention(mention, {
           onRemove: function onRemove() {
-            return removeTagById(tag.id);
+            return removeMentionById(mention.id);
           }
         })
       }));
     } else {
       var label = document.createElement("span");
       label.className = "xadk-inline-tag-label";
-      label.textContent = tag.label;
+      label.textContent = mention.displayName || mention.label;
       var close = document.createElement("span");
       close.className = "xadk-inline-tag-close";
       close.innerHTML = "×";
       close.onclick = function (event) {
         event.preventDefault();
         event.stopPropagation();
-        removeTagById(tag.id);
+        removeMentionById(mention.id);
       };
       span.append(label, close);
     }
     return span;
-  }, [removeTagById, renderTag, styles.inlineTag]);
+  }, [removeMentionById, renderMention, styles.inlineTag]);
+  var renderPartsToEditor = useCallback(function (parts) {
+    var editor = editorRef.current;
+    if (!editor) return;
+    editor.querySelectorAll("[".concat(MENTION_ATTR, "]")).forEach(function (node) {
+      var _tagRootMapRef$curren2;
+      (_tagRootMapRef$curren2 = tagRootMapRef.current.get(node)) === null || _tagRootMapRef$curren2 === void 0 || _tagRootMapRef$curren2.unmount();
+    });
+    editor.innerHTML = "";
+    parts.forEach(function (part) {
+      if (part.type === "text") {
+        if (part.text) editor.appendChild(createTextNode(part.text));
+        return;
+      }
+      var mention = part.type === "mention" ? part.mention : part.tag;
+      editor.append(buildMentionNode(mention), createTextNode(CARET_TEXT));
+    });
+  }, [buildMentionNode]);
   var setCursorAtTextEnd = useCallback(function (node) {
     var _node$textContent;
     var range = document.createRange();
@@ -155,6 +235,17 @@ var InlineTagInput = /*#__PURE__*/forwardRef(function (_ref, ref) {
     range.collapse(true);
     selection === null || selection === void 0 || selection.removeAllRanges();
     selection === null || selection === void 0 || selection.addRange(range);
+    savedRangeRef.current = range.cloneRange();
+  }, []);
+  var saveSelectionRange = useCallback(function () {
+    var editor = editorRef.current;
+    var selection = window.getSelection();
+    if (!editor || !selection || selection.rangeCount === 0) return;
+    var range = selection.getRangeAt(0);
+    if (!editor.contains(range.startContainer) || !editor.contains(range.endContainer)) {
+      return;
+    }
+    savedRangeRef.current = range.cloneRange();
   }, []);
   var restoreCursorAfterInsert = useCallback(function (node) {
     var editor = editorRef.current;
@@ -162,52 +253,80 @@ var InlineTagInput = /*#__PURE__*/forwardRef(function (_ref, ref) {
     editor.focus();
     setCursorAtTextEnd(node);
   }, [setCursorAtTextEnd]);
-  var isTagNode = function isTagNode(node) {
-    return node instanceof HTMLElement && node.hasAttribute(TAG_ATTR);
+  var isMentionNode = function isMentionNode(node) {
+    return node instanceof HTMLElement && node.hasAttribute(MENTION_ATTR);
   };
   var isOnlyCaretText = function isOnlyCaretText(text) {
     return normalizeText(text) === "";
   };
 
-  // Backspace/Delete 需要跨过零宽锚点识别相邻标签，不能只看光标所在文本节点。
-  var getTagBeforeRange = function getTagBeforeRange(range) {
+  // Backspace/Delete 需要跨过零宽锚点识别相邻 Mention，不能只看光标所在文本节点。
+  var getMentionBeforeRange = function getMentionBeforeRange(range) {
     var container = range.startContainer;
     if (container.nodeType === Node.TEXT_NODE) {
       var text = container.textContent || "";
       var beforeCursor = text.slice(0, range.startOffset);
-      if (isOnlyCaretText(beforeCursor) && isTagNode(container.previousSibling)) {
+      if (isOnlyCaretText(beforeCursor) && isMentionNode(container.previousSibling)) {
         return container.previousSibling;
       }
     }
     if (container instanceof HTMLElement) {
       var previous = container.childNodes[range.startOffset - 1];
-      if (isTagNode(previous)) return previous;
-      if ((previous === null || previous === void 0 ? void 0 : previous.nodeType) === Node.TEXT_NODE && isOnlyCaretText(previous.textContent || "") && isTagNode(previous.previousSibling)) {
+      if (isMentionNode(previous)) return previous;
+      if ((previous === null || previous === void 0 ? void 0 : previous.nodeType) === Node.TEXT_NODE && isOnlyCaretText(previous.textContent || "") && isMentionNode(previous.previousSibling)) {
         return previous.previousSibling;
       }
     }
     return null;
   };
-  var getTagAfterRange = function getTagAfterRange(range) {
+  var getMentionAfterRange = function getMentionAfterRange(range) {
     var container = range.startContainer;
     if (container.nodeType === Node.TEXT_NODE) {
       var text = container.textContent || "";
       var afterCursor = text.slice(range.startOffset);
-      if (isOnlyCaretText(afterCursor) && isTagNode(container.nextSibling)) {
+      if (isOnlyCaretText(afterCursor) && isMentionNode(container.nextSibling)) {
         return container.nextSibling;
       }
     }
     if (container instanceof HTMLElement) {
       var next = container.childNodes[range.startOffset];
-      if (isTagNode(next)) return next;
-      if ((next === null || next === void 0 ? void 0 : next.nodeType) === Node.TEXT_NODE && isOnlyCaretText(next.textContent || "") && isTagNode(next.nextSibling)) {
+      if (isMentionNode(next)) return next;
+      if ((next === null || next === void 0 ? void 0 : next.nodeType) === Node.TEXT_NODE && isOnlyCaretText(next.textContent || "") && isMentionNode(next.nextSibling)) {
         return next.nextSibling;
       }
     }
     return null;
   };
+  var moveCursorAroundMention = useCallback(function (mention, direction) {
+    var editor = editorRef.current;
+    var selection = window.getSelection();
+    if (!editor || !selection || !editor.contains(mention)) return;
+    var range = document.createRange();
+    if (direction === "before") {
+      var previous = mention.previousSibling;
+      if ((previous === null || previous === void 0 ? void 0 : previous.nodeType) === Node.TEXT_NODE) {
+        var _previous$textContent;
+        range.setStart(previous, ((_previous$textContent = previous.textContent) === null || _previous$textContent === void 0 ? void 0 : _previous$textContent.length) || 0);
+      } else {
+        range.setStartBefore(mention);
+      }
+    } else {
+      var next = mention.nextSibling;
+      if ((next === null || next === void 0 ? void 0 : next.nodeType) === Node.TEXT_NODE) {
+        var _match;
+        var leadingCaretLength = ((_match = (next.textContent || "").match(/^\u200B+/)) === null || _match === void 0 ? void 0 : _match[0].length) || 0;
+        range.setStart(next, leadingCaretLength);
+      } else {
+        range.setStartAfter(mention);
+      }
+    }
+    range.collapse(true);
+    selection.removeAllRanges();
+    selection.addRange(range);
+    savedRangeRef.current = range.cloneRange();
+  }, []);
 
-  // 读取光标在纯文本中的位置，供快捷键搜索词和 tag 插入位置复用。
+  // 读取光标在纯文本中的位置，供快捷键搜索词和 Mention 插入位置复用。
   var getOffsetInEditor = useCallback(function () {
     var editor = editorRef.current;
     var selection = window.getSelection();
@@ -224,7 +343,7 @@ var InlineTagInput = /*#__PURE__*/forwardRef(function (_ref, ref) {
         found = true;
         return;
       }
-      if (node instanceof HTMLElement && node.hasAttribute(TAG_ATTR)) return;
+      if (node instanceof HTMLElement && node.hasAttribute(MENTION_ATTR)) return;
       if (node.nodeType === Node.TEXT_NODE) {
         offset += getPlainLength(node.textContent || "");
         return;
@@ -244,8 +363,8 @@ var InlineTagInput = /*#__PURE__*/forwardRef(function (_ref, ref) {
     return index;
   };
 
-  // 删除快捷键触发片段，例如把 “@文档” 替换成一个结构化 tag，并返回删除位置对应的真实 DOM Range。
-  // 注意：纯文本 offset 不包含 tag，标签前后可能都是 offset 0；插入 tag 必须依赖真实 Range，不能再反推 offset。
+  // 删除快捷键触发片段，例如把 “@文档” 替换成一个结构化 Mention，并返回删除位置对应的真实 DOM Range。
+  // 注意：纯文本 offset 不包含 Mention，Mention 前后可能都是 offset 0；插入 Mention 必须依赖真实 Range，不能再反推 offset。
   var replaceTextRange = useCallback(function (start, end) {
     var editor = editorRef.current;
     if (!editor) return null;
@@ -281,7 +400,7 @@ var InlineTagInput = /*#__PURE__*/forwardRef(function (_ref, ref) {
     return insertRange;
   }, []);
 
-  // 浏览器拆分 Range 后可能留下空文本节点；清理后才能保证后续 tag 继续 append 在队尾。
+  // 浏览器拆分 Range 后可能留下空文本节点；清理后才能保证后续 Mention 继续 append 在队尾。
   var cleanupCaretTextNodes = useCallback(function () {
     var editor = editorRef.current;
     if (!editor) return;
@@ -297,43 +416,122 @@ var InlineTagInput = /*#__PURE__*/forwardRef(function (_ref, ref) {
       }
     });
   }, []);
-  var insertTag = useCallback(function (tag, replace) {
+
+  // Chrome 会把标签前临时输入的文字包进块级节点；文字被删空后，可能留下
+  // <div><br></div>。它没有消息语义，却会在 contenteditable 中占据一整行。
+  var cleanupEmptyStructuralNodes = useCallback(function () {
+    var editor = editorRef.current;
+    var selection = window.getSelection();
+    if (!editor) return;
+    Array.from(editor.children).forEach(function (node) {
+      if (node.hasAttribute(MENTION_ATTR)) return;
+      if (node.querySelector("[".concat(MENTION_ATTR, "]"))) return;
+      if (normalizeText(node.textContent || "")) return;
+      var range = selection !== null && selection !== void 0 && selection.rangeCount ? selection.getRangeAt(0) : null;
+      var nodeIndex = getNodeIndex(node);
+      var containsCursor = Boolean(range && range.collapsed && (range.startContainer === node || node.contains(range.startContainer) || range.startContainer === editor && (range.startOffset === nodeIndex || range.startOffset === nodeIndex + 1)));
+      if (containsCursor && selection) {
+        // 光标紧邻 contenteditable=false 的 Mention 时，单纯删除 <br> 会让 Chrome
+        // 再次生成它。替换成零宽文本锚点，既能承接光标，也不会增加行高。
+        var caretNode = createTextNode(CARET_TEXT);
+        node.replaceWith(caretNode);
+        var nextRange = document.createRange();
+        nextRange.setStart(caretNode, CARET_TEXT.length);
+        nextRange.collapse(true);
+        selection.removeAllRanges();
+        selection.addRange(nextRange);
+        savedRangeRef.current = nextRange.cloneRange();
+        return;
+      }
+      node.remove();
+    });
+  }, []);
+  useEffect(function () {
     var editor = editorRef.current;
     if (!editor) return;
+
+    // 某些业务容器会截断 React 委托事件；直接监听编辑器的原生 input，确保删除事务结束后
+    // 仍能清理 Chrome 在不可编辑 Mention 前生成的占行 <br>。仅处理 delete*，不影响 Enter 换行。
+    var handleNativeDelete = function handleNativeDelete(event) {
+      if (!(event instanceof InputEvent)) return;
+      if (!event.inputType.startsWith("delete")) return;
+      if (structuralCleanupFrameRef.current !== null) {
+        window.cancelAnimationFrame(structuralCleanupFrameRef.current);
+      }
+      structuralCleanupFrameRef.current = window.requestAnimationFrame(function () {
+        structuralCleanupFrameRef.current = null;
+        cleanupEmptyStructuralNodes();
+        cleanupCaretTextNodes();
+      });
+    };
+    editor.addEventListener("input", handleNativeDelete);
+    return function () {
+      return editor.removeEventListener("input", handleNativeDelete);
+    };
+  }, [cleanupCaretTextNodes, cleanupEmptyStructuralNodes]);
+  var insertMention = useCallback(function (mention, replace) {
+    var editor = editorRef.current;
+    if (!editor) return;
+    // 工具栏/弹窗会先抢走焦点；必须在 focus 之前保存当前 Selection，
+    // 否则浏览器新建在输入框开头的 Range 会覆盖最后一次真实光标位置。
+    var selectionBeforeFocus = window.getSelection();
+    var activeRangeBeforeFocus = selectionBeforeFocus !== null && selectionBeforeFocus !== void 0 && selectionBeforeFocus.rangeCount && editor.contains(selectionBeforeFocus.getRangeAt(0).startContainer) ? selectionBeforeFocus.getRangeAt(0).cloneRange() : null;
+    var savedRangeBeforeFocus = savedRangeRef.current && editor.contains(savedRangeRef.current.startContainer) ? savedRangeRef.current.cloneRange() : null;
+    var rangeBeforeFocus = activeRangeBeforeFocus || savedRangeBeforeFocus;
     editor.focus();
-    latestTagsRef.current = [].concat(_toConsumableArray(latestTagsRef.current.filter(function (item) {
-      return item.id !== tag.id;
-    })), [tag]);
+    latestMentionsRef.current = [].concat(_toConsumableArray(latestMentionsRef.current.filter(function (item) {
+      return item.id !== mention.id;
+    })), [mention]);
     var insertRange = null;
     if (replace) {
       insertRange = replaceTextRange(replace.start, replace.end);
       cleanupCaretTextNodes();
     }
-    var tagNode = buildTagNode(tag);
+    // 浏览器会在空 contenteditable 中生成 <div><br> 等占位块。
+    // 空编辑器插入首个 Mention 前先清掉这些无语义节点，避免标签被放进第二个视觉行。
+    var isSemanticallyEmpty = !getPlainText() && !editor.querySelector("[".concat(MENTION_ATTR, "]"));
+    if (isSemanticallyEmpty) {
+      editor.innerHTML = "";
+      savedRangeRef.current = null;
+      insertRange = null;
+    }
+    var mentionNode = buildMentionNode(mention);
     var caretNode = createTextNode(CARET_TEXT);
-    var selection = window.getSelection();
-    var range = insertRange || (selection !== null && selection !== void 0 && selection.rangeCount ? selection.getRangeAt(0) : null);
+    var range = insertRange || rangeBeforeFocus;
     if (range && editor.contains(range.startContainer)) {
-      // 用 DocumentFragment 一次性插入，避免连续 insertNode 导致 tag/caret 顺序被浏览器 Range 状态打乱。
+      // 用 DocumentFragment 一次性插入，避免连续 insertNode 导致 mention/caret 顺序被浏览器 Range 状态打乱。
       var fragment = document.createDocumentFragment();
-      fragment.append(tagNode, caretNode);
+      fragment.append(mentionNode, caretNode);
       range.insertNode(fragment);
     } else {
-      editor.append(tagNode, caretNode);
+      editor.append(mentionNode, caretNode);
     }
     cleanupCaretTextNodes();
     lastInsertedCaretRef.current = caretNode;
     setCursorAtTextEnd(caretNode);
     emitChange();
 
-    // 关闭快捷列表和父组件同步 tags/value 会触发一次 React 更新；
-    // 下一帧再恢复到刚插入 tag 后的零宽锚点，避免光标被 focus 或重渲染带回旧位置。
+    // 关闭快捷列表和父组件同步 mentions/value 会触发一次 React 更新；
+    // 下一帧再恢复到刚插入 Mention 后的零宽锚点，避免光标被 focus 或重渲染带回旧位置。
     window.requestAnimationFrame(function () {
       if (lastInsertedCaretRef.current === caretNode) {
         restoreCursorAfterInsert(caretNode);
       }
     });
-  }, [buildTagNode, cleanupCaretTextNodes, emitChange, replaceTextRange, restoreCursorAfterInsert, setCursorAtTextEnd]);
+  }, [buildMentionNode, cleanupCaretTextNodes, emitChange, getPlainText, replaceTextRange, restoreCursorAfterInsert, setCursorAtTextEnd]);
+  useEffect(function () {
+    document.addEventListener("selectionchange", saveSelectionRange);
+    return function () {
+      document.removeEventListener("selectionchange", saveSelectionRange);
+    };
+  }, [saveSelectionRange]);
+  useEffect(function () {
+    return function () {
+      if (structuralCleanupFrameRef.current !== null) {
+        window.cancelAnimationFrame(structuralCleanupFrameRef.current);
+      }
+    };
+  }, []);
   useImperativeHandle(ref, function () {
     return {
       focus: function focus() {
@@ -341,65 +539,150 @@ var InlineTagInput = /*#__PURE__*/forwardRef(function (_ref, ref) {
         return (_editorRef$current = editorRef.current) === null || _editorRef$current === void 0 ? void 0 : _editorRef$current.focus();
       },
       getText: getPlainText,
+      getParts: getParts,
       getCursorOffset: getOffsetInEditor,
-      insertTag: insertTag
+      insertMention: insertMention,
+      insertTag: insertMention
     };
-  }, [getOffsetInEditor, getPlainText, insertTag]);
-  useEffect(function () {
-    var editor = editorRef.current;
-    if (!editor || editor.childNodes.length > 0) return;
-    if (value) editor.appendChild(createTextNode(value));
-    tags.forEach(function (tag) {
-      return editor.append(buildTagNode(tag), createTextNode(CARET_TEXT));
-    });
-  }, []);
-
-  // 外部受控 tags 变化时，同步补齐或删除 DOM 中的 tag 节点。
-  useEffect(function () {
+  }, [getOffsetInEditor, getParts, getPlainText, insertMention]);
+  useIsomorphicLayoutEffect(function () {
     var editor = editorRef.current;
     if (!editor) return;
-    var existingNodes = Array.from(editor.querySelectorAll("[".concat(TAG_ATTR, "]")));
-    var nextTagMap = new Map(tags.map(function (tag) {
-      return [tag.id, tag];
-    }));
-    var existingIds = new Set(existingNodes.map(function (node) {
-      return node.dataset.xadkInlineTagId || "";
-    }));
-    existingNodes.forEach(function (node) {
-      var tagId = node.dataset.xadkInlineTagId || "";
-      if (!nextTagMap.has(tagId)) {
-        removeTagNode(node);
-      }
-    });
-    tags.forEach(function (tag) {
-      if (existingIds.has(tag.id)) return;
-      editor.append(buildTagNode(tag), createTextNode(CARET_TEXT));
+
+    // 默认片段只在空输入首次挂载时灌入，避免外部重新渲染覆盖用户正在编辑的内容。
+    if (!defaultInputPartsAppliedRef.current && defaultInputParts !== null && defaultInputParts !== void 0 && defaultInputParts.length && !value && mentions.length === 0) {
+      defaultInputPartsAppliedRef.current = true;
+      // emitChange 的受控回写要到下一次 render 才生效；跳过本轮紧随其后的空值清理，
+      // 避免刚渲染的默认 Mention 被旧的空 value/mentions 立即移除。
+      skipEmptyCleanupOnceRef.current = true;
+      renderPartsToEditor(defaultInputParts);
+      emitChange();
+      return;
+    }
+    var incomingMentionIds = mentions.map(function (mention) {
+      return mention.id;
+    }).join("|");
+    var lastEmittedState = lastEmittedStateRef.current;
+    var isInternalControlledEcho = value === lastEmittedState.value && incomingMentionIds === lastEmittedState.mentionIds;
+    if (isInternalControlledEcho && editor.childNodes.length > 0) return;
+    renderPartsToEditor([].concat(_toConsumableArray(value ? [{
+      type: "text",
+      text: value
+    }] : []), _toConsumableArray(mentions.map(function (mention) {
+      return {
+        type: "mention",
+        mention: mention
+      };
+    }))));
+    setHasContent(Boolean(value || mentions.length));
+
+    // 外部主动写入 value/mentions 后，需要在首帧绘制前同步 DOM；若输入区已有焦点，则把光标放在内容末尾。
+    var lastTextNode = Array.from(editor.childNodes).reverse().find(function (node) {
+      return node.nodeType === Node.TEXT_NODE;
     });
-  }, [buildTagNode, removeTagNode, tags]);
-  useEffect(function () {
+    if (document.activeElement === editor && lastTextNode) {
+      setCursorAtTextEnd(lastTextNode);
+    }
+  }, [defaultInputParts, emitChange, renderPartsToEditor, setCursorAtTextEnd, mentions, value]);
+  useIsomorphicLayoutEffect(function () {
     var editor = editorRef.current;
     if (!editor) return;
-    if (!value && tags.length === 0 && editor.childNodes.length > 0) {
-      editor.querySelectorAll("[".concat(TAG_ATTR, "]")).forEach(function (node) {
-        var _tagRootMapRef$curren2;
-        (_tagRootMapRef$curren2 = tagRootMapRef.current.get(node)) === null || _tagRootMapRef$curren2 === void 0 || _tagRootMapRef$curren2.unmount();
+    if (skipEmptyCleanupOnceRef.current) {
+      skipEmptyCleanupOnceRef.current = false;
+      return;
+    }
+    if (!value && mentions.length === 0 && editor.childNodes.length > 0) {
+      editor.querySelectorAll("[".concat(MENTION_ATTR, "]")).forEach(function (node) {
+        var _tagRootMapRef$curren3;
+        (_tagRootMapRef$curren3 = tagRootMapRef.current.get(node)) === null || _tagRootMapRef$curren3 === void 0 || _tagRootMapRef$curren3.unmount();
       });
       editor.innerHTML = "";
     }
-  }, [tags.length, value]);
+  }, [mentions.length, value]);
   var handleInput = function handleInput() {
-    if (!composingRef.current) emitChange();
+    if (!composingRef.current) {
+      cleanupEmptyStructuralNodes();
+      cleanupCaretTextNodes();
+      emitChange();
+
+      // Chrome 可能在 input 回调返回后才补上用于承接光标的 <br>；下一帧再归一化一次。
+      if (structuralCleanupFrameRef.current !== null) {
+        window.cancelAnimationFrame(structuralCleanupFrameRef.current);
+      }
+      structuralCleanupFrameRef.current = window.requestAnimationFrame(function () {
+        structuralCleanupFrameRef.current = null;
+        cleanupEmptyStructuralNodes();
+        cleanupCaretTextNodes();
+      });
+    }
+  };
+  var handlePaste = function handlePaste(event) {
+    event.preventDefault();
+    var editor = editorRef.current;
+    if (!editor) return;
+
+    // 始终按 text/plain 粘贴，避免消息气泡的背景色等 HTML 样式进入 contenteditable。
+    var text = event.clipboardData.getData("text/plain");
+    if (!text) return;
+    var parts = parseMarkdownResourceLinksAsParts(text);
+    var selection = window.getSelection();
+    var range = selection !== null && selection !== void 0 && selection.rangeCount && editor.contains(selection.getRangeAt(0).startContainer) ? selection.getRangeAt(0) : null;
+    var fragment = document.createDocumentFragment();
+    var lastTextNode = null;
+    var _iterator = _createForOfIteratorHelper(parts),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var part = _step.value;
+        if (part.type === "text") {
+          lastTextNode = createTextNode(part.text);
+          fragment.append(lastTextNode);
+          continue;
+        }
+        latestMentionsRef.current = [].concat(_toConsumableArray(latestMentionsRef.current), [part.mention]);
+        fragment.append(buildMentionNode(part.mention));
+        lastTextNode = createTextNode(CARET_TEXT);
+        fragment.append(lastTextNode);
+      }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+    if (range) {
+      range.deleteContents();
+      range.insertNode(fragment);
+    } else {
+      editor.append(fragment);
+    }
+    cleanupCaretTextNodes();
+    if (lastTextNode) setCursorAtTextEnd(lastTextNode);
+    emitChange();
   };
   var handleKeyDown = function handleKeyDown(event) {
-    if (event.key === "Backspace" || event.key === "Delete") {
+    if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
       var selection = window.getSelection();
       if (selection !== null && selection !== void 0 && selection.rangeCount) {
         var range = selection.getRangeAt(0);
         if (range.collapsed) {
-          var targetTag = event.key === "Backspace" ? getTagBeforeRange(range) : getTagAfterRange(range);
-          if (targetTag) {
+          var targetMention = event.key === "ArrowLeft" ? getMentionBeforeRange(range) : getMentionAfterRange(range);
+          if (targetMention) {
             event.preventDefault();
-            removeTagById(targetTag.dataset.xadkInlineTagId || "");
+            moveCursorAroundMention(targetMention, event.key === "ArrowLeft" ? "before" : "after");
+            return;
+          }
+        }
+      }
+    }
+    if (event.key === "Backspace" || event.key === "Delete") {
+      var _selection = window.getSelection();
+      if (_selection !== null && _selection !== void 0 && _selection.rangeCount) {
+        var _range = _selection.getRangeAt(0);
+        if (_range.collapsed) {
+          var _targetMention = event.key === "Backspace" ? getMentionBeforeRange(_range) : getMentionAfterRange(_range);
+          if (_targetMention) {
+            event.preventDefault();
+            removeMentionById(_targetMention.dataset.xadkInlineMentionId || "");
             return;
           }
         }
@@ -407,10 +690,15 @@ var InlineTagInput = /*#__PURE__*/forwardRef(function (_ref, ref) {
     }
     onKeyDown === null || onKeyDown === void 0 || onKeyDown(event);
   };
-  return /*#__PURE__*/_jsx("div", {
+
+  // placeholder 只由受控 value/mentions 派生，避免从 contenteditable DOM 读取导致外部插入 Mention 后状态滞后一帧。
+  var showPlaceholder = !hasContent;
+  return /*#__PURE__*/_jsxs("div", {
     className: styles.inlineInputWrapper,
-    "data-placeholder": placeholder,
-    children: /*#__PURE__*/_jsx("div", {
+    children: [showPlaceholder && placeholder && /*#__PURE__*/_jsx("div", {
+      className: styles.inlinePlaceholder,
+      children: placeholder
+    }), /*#__PURE__*/_jsx("div", {
       ref: editorRef,
       className: styles.inlineInput,
       contentEditable: !disabled,
@@ -418,18 +706,27 @@ var InlineTagInput = /*#__PURE__*/forwardRef(function (_ref, ref) {
       role: "textbox",
       "aria-multiline": "true",
       onInput: handleInput,
+      onPaste: handlePaste,
       onKeyDown: handleKeyDown,
-      onKeyUp: onKeyUp,
+      onKeyUp: function onKeyUp(event) {
+        cleanupEmptyStructuralNodes();
+        cleanupCaretTextNodes();
+        saveSelectionRange();
+        _onKeyUp === null || _onKeyUp === void 0 || _onKeyUp(event);
+      },
+      onMouseUp: saveSelectionRange,
+      onFocus: saveSelectionRange,
       onCompositionStart: function onCompositionStart() {
         composingRef.current = true;
+        // 中文 IME 在 compositionend 前不会触发受控 value 更新；候选输入一出现就应隐藏 placeholder。
+        setHasContent(true);
       },
       onCompositionEnd: function onCompositionEnd() {
         composingRef.current = false;
         emitChange();
       },
-      "data-empty": !getPlainText() && getOrderedTags().length === 0,
       "data-cursor-offset": getOffsetInEditor()
-    })
+    })]
   });
 });
 InlineTagInput.displayName = "InlineTagInput";