iter(g132): 新增 @提及输入 mentions

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T07:21:05.139Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T07:22:32.759Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -1758,6 +1758,34 @@ document.body.append(floatButton({ icon: '+', label: '新建工单', position: '
 
 现场演示：apps/docs/demo.html#sec-floatbutton
 
+### mentions — @提及输入 Mentions
+
+参数：
+
+- items（必填）：MentionItem[] —— 候选池：每项含 name（插入正文的名字）、label（显示名）、description（说明）、keywords（只参与过滤的额外匹配词）
+- value：Signal<string> —— 受控文本信号；不传则组件内部维护（拿不到外部读取时不要传）
+- rows（默认 3）：number —— 输入框行数
+- placeholder：string —— 占位文案
+- onSelect（回调）：(item: MentionItem) => void —— 选中某人后的回调（弹层已收起，正文已替换）
+- onInput（回调）：(text: string) => void —— 每次输入的回调，参数为当前全文（已写回 value 信号）
+
+示例：
+
+```
+const text = signal(''); mentions({ items: [{ name: 'zhangsan', label: '张三', description: '前端', keywords: ['zs'] }], value: text, placeholder: '输入 @ 叫人', onSelect: (it) => toast.info(it.label) })
+```
+
+手把手：
+
+1. 在输入框里键入 @ 触发弹层，继续打字按 name / keywords 过滤（拼音、工号放 keywords，不出现在候选行里）
+2. 键盘：↑↓ 环形移动高亮、Enter 或 Tab 选中、Esc 只收这一层弹层（stopPropagation，不会连带关掉外层弹窗）
+3. 选中后组件按光标位置把 @片段替换成「@名字 + 空格」，光标落在其后，可以接着打字
+4. 受控用法：传 value 信号并在 onSelect / onInput 里读最新全文；外部改信号会同步回输入框，别同时再手写 input 事件
+5. 弹层贴在输入框下沿而非跟随光标行（多行输入里更稳定，也不会被行高算错），需要跟随光标请自绘
+6. 要限制可选人范围就在 items 上做过滤，组件不做远程搜索；远程场景用 onInput 拉数据后重建 items
+
+现场演示：apps/docs/demo.html#sec-mentions
+
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
@@ -1825,6 +1853,7 @@ API 速览：
 - typography(props)：排版文本，variant 决定语义（标题出 h1-h5 / 段落出 p / 行内出 span），支持语义色、装饰位、对齐、多行截断与复制按钮
 - grid(props, ...children)：栅格容器，columns 固定列数或 min 走 auto-fit 自适应列宽，gutter 统一列间距，窄屏自动降为单列
 - floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label
+- mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value
 
 一行用法：