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

packages/skin/ui/src/index.ts

@@ -63,3 +63,4 @@ export { calendar } from './calendar.js';
 export { typography } from './typography.js';
 export { grid } from './grid.js';
 export { floatButton } from './floatButton.js';
+export { mentions } from './mentions.js';

packages/skin/ui/src/mentions.ts

@@ -0,0 +1,114 @@
+import { effect, h, signal } from '@ui-arch/frame';
+import type { MentionItem, MentionsProps } from './types.js';
+
+// 每个实例的 listbox id 前缀，保证 aria-activedescendant 唯一
+let seq = 0;
+
+/*** 取光标前的 @ 触发词（不含 @ 本身）：没有未闭合的 @ 片段时返回 null ***/
+function tokenBefore(text: string, caret: number): string | null {
+  const match = /@([^\s@]*)$/.exec(text.slice(0, caret));
+  return match ? match[1] : null;
+}
+
+/*** 用选中的名字替换光标前的 @片段，返回替换后的全文与新光标位置 ***/
+function applyPick(text: string, caret: number, name: string): { text: string; caret: number } {
+  const head = text.slice(0, caret).replace(/@[^\s@]*$/, `@${name} `);
+  return { text: head + text.slice(caret), caret: head.length };
+}
+
+/*** @提及输入：textarea 内键入 @ 弹候选，↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层；弹层贴输入框下沿，选中按光标替换 @片段 ***/
+export function mentions(props: MentionsProps): HTMLElement {
+  const uid = `ua-mentions-${++seq}`;
+  const items = props.items;
+  const value = props.value ?? signal('');
+  const open = signal(false); // 弹层开合
+  const query = signal(''); // 当前 @ 后的过滤词
+  const active = signal(0); // 高亮项下标
+  const input = h('textarea', {
+    class: 'ua-mentions-input',
+    rows: String(props.rows ?? 3),
+    placeholder: props.placeholder ?? '',
+    'aria-autocomplete': 'list',
+    'aria-controls': uid,
+    'aria-expanded': 'false',
+  }) as HTMLTextAreaElement;
+  input.value = value();
+  const list = h('div', { class: 'ua-mentions-pop', role: 'listbox', id: uid });
+  const wrap = h('div', { class: 'ua-mentions' }, input, list);
+
+  // 候选：空过滤词给全量，否则按名字 / 关键词做包含匹配
+  const filtered = (): MentionItem[] => (query()
+    ? items.filter((it) => it.name.includes(query()) || (it.keywords ?? []).some((k) => k.includes(query())))
+    : items);
+
+  /*** 重绘弹层：同步显隐、高亮项与 aria-activedescendant（无候选时不开层） ***/
+  const paint = (): void => {
+    const shown = filtered();
+    const visible = open() && shown.length > 0;
+    wrap.classList.toggle('is-open', visible);
+    input.setAttribute('aria-expanded', String(visible));
+    list.replaceChildren(...shown.map((item, i) => h('div', {
+      class: `ua-mentions-item${i === active() ? ' is-active' : ''}`,
+      role: 'option',
+      id: `${uid}-${i}`,
+      'aria-selected': i === active() ? 'true' : 'false',
+      onmousedown: (e: Event) => { e.preventDefault(); pick(item); }, // 阻止默认让 textarea 不失焦
+    }, h('span', { class: 'ua-mentions-name' }, item.label),
+    item.description ? h('span', { class: 'ua-mentions-desc' }, item.description) : null)));
+    if (visible) input.setAttribute('aria-activedescendant', `${uid}-${active()}`);
+    else input.removeAttribute('aria-activedescendant');
+  };
+
+  /*** 选中候选：替换光标前的 @片段、写回信号、光标落到插入文本之后 ***/
+  const pick = (item: MentionItem): void => {
+    const caret = input.selectionStart ?? input.value.length;
+    const next = applyPick(input.value, caret, item.name);
+    input.value = next.text;
+    value(next.text);
+    input.setSelectionRange(next.caret, next.caret);
+    input.focus();
+    open(false);
+    query('');
+    paint();
+    props.onSelect?.(item);
+  };
+
+  input.addEventListener('input', () => {
+    value(input.value);
+    props.onInput?.(input.value);
+    const token = tokenBefore(input.value, input.selectionStart ?? input.value.length);
+    query(token ?? '');
+    active(0); // 每次输入重新从第一项开始高亮
+    open(token !== null);
+    paint();
+  });
+
+  input.addEventListener('keydown', (e) => {
+    if (!open()) return; // 未开层时所有按键交给浏览器
+    const shown = filtered();
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      e.stopPropagation(); // 只收本层，不连带外层弹层
+      open(false);
+      paint();
+      return;
+    }
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+      e.preventDefault();
+      active((active() + (e.key === 'ArrowDown' ? 1 : -1) + shown.length) % shown.length); // 环形移动
+      paint();
+      return;
+    }
+    if ((e.key === 'Enter' || e.key === 'Tab') && shown.length) {
+      e.preventDefault();
+      pick(shown[Math.min(active(), shown.length - 1)]);
+    }
+  });
+
+  input.addEventListener('blur', () => { open(false); paint(); }); // 失焦收起
+  effect(() => {
+    const outer = value();
+    if (outer !== input.value) input.value = outer; // 外部改信号时同步输入框
+  });
+  return wrap;
+}

packages/skin/ui/src/types.ts

@@ -777,4 +777,22 @@ export interface FloatButtonProps {
   onClick?: () => void;      // 点击回调
 }
 
+/*** @提及候选项 ***/
+export interface MentionItem {
+  name: string;         // 插入正文的名字（@ 之后的部分，如 zhangsan）
+  label: string;        // 候选行显示名称（如 张三）
+  description?: string; // 候选行右侧说明（部门 / 邮箱）
+  keywords?: string[];  // 额外匹配词（拼音、工号），不显示只参与过滤
+}
+
+/*** @提及输入入参 ***/
+export interface MentionsProps {
+  items: MentionItem[];          // 候选池：键入 @ 后按名字 / 关键词过滤
+  value?: Signal<string>;        // 受控文本信号；不传则内部维护
+  rows?: number;                 // 输入框行数；缺省 3
+  placeholder?: string;          // 占位文案
+  onSelect?: (item: MentionItem) => void; // 选中某人后的回调（弹层已收起）
+  onInput?: (text: string) => void;       // 每次输入的回调，参数为当前全文
+}
+
 export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方

packages/skin/ui/ua.manifest.json

@@ -77,7 +77,8 @@
       "calendar(props)：月历，整月网格内嵌页面（排期 / 值班 / 日程），每日可带 marker 标记文案，方向键漫游 + Enter 选中，翻月走 onMonthChange",
       "typography(props)：排版文本，variant 决定语义（标题出 h1-h5 / 段落出 p / 行内出 span），支持语义色、装饰位、对齐、多行截断与复制按钮",
       "grid(props, ...children)：栅格容器，columns 固定列数或 min 走 auto-fit 自适应列宽，gutter 统一列间距，窄屏自动降为单列",
-      "floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label"
+      "floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label",
+      "mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -3133,6 +3134,56 @@
           "右下角已被 backTop 占用，页面同时有返回顶部时用 position: 'left-bottom'",
           "纯展示 + 单回调，没有选中态与开合状态；需要多级操作请用 menu / popover 挂在 onClick 上"
         ]
+      },
+      {
+        "id": "mentions",
+        "title": "@提及输入 Mentions",
+        "demo": "sec-mentions",
+        "props": [
+          {
+            "n": "items",
+            "t": "MentionItem[]",
+            "r": 1,
+            "d": "候选池：每项含 name（插入正文的名字）、label（显示名）、description（说明）、keywords（只参与过滤的额外匹配词）"
+          },
+          {
+            "n": "value",
+            "t": "Signal<string>",
+            "d": "受控文本信号；不传则组件内部维护（拿不到外部读取时不要传）"
+          },
+          {
+            "n": "rows",
+            "t": "number",
+            "df": "3",
+            "d": "输入框行数"
+          },
+          {
+            "n": "placeholder",
+            "t": "string",
+            "d": "占位文案"
+          },
+          {
+            "n": "onSelect",
+            "t": "(item: MentionItem) => void",
+            "k": 1,
+            "d": "选中某人后的回调（弹层已收起，正文已替换）"
+          },
+          {
+            "n": "onInput",
+            "t": "(text: string) => void",
+            "k": 1,
+            "d": "每次输入的回调，参数为当前全文（已写回 value 信号）"
+          }
+        ],
+        "example": "const text = signal(''); mentions({ items: [{ name: 'zhangsan', label: '张三', description: '前端', keywords: ['zs'] }], value: text, placeholder: '输入 @ 叫人', onSelect: (it) => toast.info(it.label) })",
+        "steps": [
+          "在输入框里键入 @ 触发弹层，继续打字按 name / keywords 过滤（拼音、工号放 keywords，不出现在候选行里）",
+          "键盘：↑↓ 环形移动高亮、Enter 或 Tab 选中、Esc 只收这一层弹层（stopPropagation，不会连带关掉外层弹窗）",
+          "选中后组件按光标位置把 @片段替换成「@名字 + 空格」，光标落在其后，可以接着打字",
+          "受控用法：传 value 信号并在 onSelect / onInput 里读最新全文；外部改信号会同步回输入框，别同时再手写 input 事件",
+          "弹层贴在输入框下沿而非跟随光标行（多行输入里更稳定，也不会被行高算错），需要跟随光标请自绘",
+          "要限制可选人范围就在 items 上做过滤，组件不做远程搜索；远程场景用 onInput 拉数据后重建 items"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -4151,3 +4151,80 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
     transform: none;
   }
 }
+
+/* —— @提及输入：弹层贴输入框下沿，候选行高亮走淡色底 —— */
+.ua-mentions {
+  position: relative;
+  display: inline-block;
+  width: 100%;
+}
+.ua-mentions-input {
+  width: 100%;
+  box-sizing: border-box;
+  padding: var(--ua-space-2) var(--ua-space-3);
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-md);
+  background: var(--ua-color-surface);
+  color: var(--ua-color-text);
+  font: inherit;
+  font-size: var(--ua-font-size-md);
+  line-height: 1.6;
+  resize: vertical;
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+.ua-mentions-input:focus {
+  outline: none;
+  border-color: var(--ua-color-accent);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--ua-color-accent) 22%, transparent);
+}
+.ua-mentions-pop {
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: calc(100% + 4px);
+  z-index: 30;
+  display: none;
+  max-height: 220px;
+  overflow-y: auto;
+  padding: var(--ua-space-1);
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-md);
+  background: var(--ua-color-surface);
+  box-shadow: 0 12px 28px color-mix(in srgb, var(--ua-color-text) 16%, transparent);
+}
+.ua-mentions.is-open .ua-mentions-pop {
+  display: block;
+  animation: ua-mentions-in 0.15s ease;
+}
+.ua-mentions-item {
+  display: flex;
+  align-items: baseline;
+  gap: var(--ua-space-2);
+  padding: var(--ua-space-2) var(--ua-space-2);
+  border-radius: var(--ua-radius-sm);
+  cursor: pointer;
+  transition: background 0.15s ease;
+}
+.ua-mentions-item.is-active {
+  background: color-mix(in srgb, var(--ua-color-accent) 10%, transparent); /* 选中态低视觉比重 */
+}
+.ua-mentions-name {
+  color: var(--ua-color-text);
+}
+.ua-mentions-desc {
+  color: var(--ua-color-text-muted);
+  font-size: var(--ua-font-size-sm);
+}
+@keyframes ua-mentions-in {
+  from { opacity: 0; transform: translateY(-4px); }
+  to { opacity: 1; transform: none; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .ua-mentions.is-open .ua-mentions-pop {
+    animation: none;
+  }
+  .ua-mentions-input,
+  .ua-mentions-item {
+    transition: none;
+  }
+}