iter(g49): 新增 autoComplete 自动补全组件

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T04:11:34.965Z",
+  "generatedAt": "2026-10-26T04:12:36.698Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -190,7 +190,8 @@
           "result(props)：结果页，status 四档语义色 + 标题 + 说明 + 操作区，用于提交完成/校验失败等终态",
           "transfer(props)：穿梭框，左右两栏勾选后整体搬运，targetKeys 信号双向绑定，两栏各自搜索与全选（含半选），禁用条目不参与搬运也不可勾选",
           "cascader(props)：级联选择，多列联动面板（悬停下钻 / 点击提交），value 为路径数组信号，changeOnSelect 允许停在中间层，全键盘可操作",
-          "splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号"
+          "splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号",
+          "autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想"
         ],
         "keyTypes": [
           "ButtonProps",
@@ -2195,6 +2196,62 @@
               "direction 传 vertical 变为上下分栏，键盘方向键与光标同步切换",
               "传入 sizes 信号即受控，外部写入可做「预设布局」切换（如 1:1 / 2:1）"
             ]
+          },
+          {
+            "id": "autoComplete",
+            "title": "自动补全 AutoComplete",
+            "demo": "sec-autocomplete",
+            "props": [
+              {
+                "n": "options",
+                "t": "AutoCompleteOption[] | ((q: string) => AutoCompleteOption[])",
+                "r": 1,
+                "d": "候选项：静态列表或按关键字计算的函数（可远程联想）"
+              },
+              {
+                "n": "value",
+                "t": "Signal<string>",
+                "d": "输入值信号；不传则内部维护，传了即外部受控"
+              },
+              {
+                "n": "placeholder",
+                "t": "string",
+                "d": "占位文案，同时作为无障碍名称"
+              },
+              {
+                "n": "emptyText",
+                "t": "string",
+                "d": "无匹配时的提示文案；缺省「无匹配项」"
+              },
+              {
+                "n": "maxItems",
+                "t": "number",
+                "d": "最多展示条数；缺省 8"
+              },
+              {
+                "n": "disabled",
+                "t": "boolean | Signal<boolean>",
+                "d": "禁用输入与弹层"
+              },
+              {
+                "n": "onInput",
+                "t": "(query: string) => void",
+                "d": "每次输入回调，适合触发远程请求"
+              },
+              {
+                "n": "onSelect",
+                "t": "(option: AutoCompleteOption) => void",
+                "d": "选中回调（点击或 Enter）"
+              }
+            ],
+            "example": "autoComplete({ value: acValue, placeholder: '输入组件名', options: [{ value: 'dataTable', hint: '表格' }], onSelect: (o) => toast.success(o.value) })",
+            "steps": [
+              "输入任何字符即按包含匹配（忽略大小写）过滤候选，空串时弹层不展开",
+              "↑↓ 在候选间环形移动并高亮，Enter 选中，Esc 收起，Tab 失焦也会收起",
+              "候选行支持右侧 hint（分类 / 拼音），选中后值写回输入框并触发 onSelect",
+              "options 传函数时每次输入都会用当前关键字调用，可在此发起远程请求并返回新数组",
+              "value 传信号即受控：外部写入会同步回填输入框内容"
+            ]
           }
         ]
       },

AGENTS.md

@@ -21,7 +21,7 @@
 
 - `packages/core/table-core`（@ui-arch/table-core）：Headless 表格逻辑内核
 - `packages/core/frame`（@ui-arch/frame）：signal + hyperscript 微框架
-- `packages/skin/ui`（@ui-arch/ui）：47 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
+- `packages/skin/ui`（@ui-arch/ui）：48 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
 - `packages/design/tokens`（@ui-arch/tokens）：设计令牌
 - `packages/tools/cli`（@ui-arch/cli）：`ua` 命令行 + MCP 注册表服务（private）
 - `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html

ARCHITECTURE.md

@@ -34,7 +34,7 @@ ui-arch-mvp/
 │   │   ├── table-core/       # 表格状态内核
 │   │   └── frame/            # 信号 + hyperscript 微框架
 │   ├── skin/                 # 皮肤层（DOM 组件，可发布）
-│   │   └── ui/               # 47 个组件 + ui.css
+│   │   └── ui/               # 48 个组件 + ui.css
 │   ├── design/               # 资产层（可发布）
 │   │   └── tokens/           # --ua-* 设计令牌
 │   └── tools/                # 工程层（private，不发布）

README.md

@@ -11,13 +11,13 @@ npm run demo            # 打开演示：apps/demo/dist/demo.html
 npm run docs            # 生成人类文档站 apps/docs/index.html + Agent 全量文档 llms-full.txt
 ```
 
-## 组件（共 47 个）
+## 组件（共 48 个）
 
 <!-- ua:components -->
-accordion · alert · avatar · badge · breadcrumb · button · carousel · card · cascader · checkbox · dataTable · descriptions · divider · drawer · empty · form · image · inputNumber · list · menu · modal · notification · pagination · popover · progress · radioGroup · rate · result · segmented · select · skeleton · slider · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · transfer · tree · upload
+accordion · alert · autoComplete · avatar · badge · breadcrumb · button · carousel · card · cascader · checkbox · dataTable · descriptions · divider · drawer · empty · form · image · inputNumber · list · menu · modal · notification · pagination · popover · progress · radioGroup · rate · result · segmented · select · skeleton · slider · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · transfer · tree · upload
 <!-- /ua:components -->
 
-分组：表单（button / textField / inputNumber / textarea / checkbox / switchButton / select / radioGroup / slider / rate / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / image / carousel）、其他（divider / splitter）。
+分组：表单（button / textField / inputNumber / textarea / checkbox / switchButton / select / radioGroup / slider / rate / autoComplete / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / image / carousel）、其他（divider / splitter）。
 
 ## 可访问性约定
 
@@ -31,7 +31,7 @@ accordion · alert · avatar · badge · breadcrumb · button · carousel · car
 |---|---|
 | `packages/core/frame` | @ui-arch/frame：signal / computed / effect + hyperscript（无虚拟 DOM） |
 | `packages/core/table-core` | @ui-arch/table-core：headless 表格（filter → sort → paginate 派生管线） |
-| `packages/skin/ui` | @ui-arch/ui：47 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
+| `packages/skin/ui` | @ui-arch/ui：48 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
 | `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） |
 | `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server |
 | `apps/demo` | 交互演示（esbuild 打包成单文件） |

apps/demo/main.ts

@@ -10,6 +10,7 @@ const IMG_DEMO = 'data:image/svg+xml;utf8,' + encodeURIComponent(
 import {
   accordion,
   alert,
+  autoComplete,
   avatar,
   badge,
   breadcrumb,
@@ -185,6 +186,7 @@ const listPick = signal(''); // 列表点击选中的条目标题
 const slideIndex = signal(0); // 轮播当前下标（外部受控演示）
 const cascaderPath = signal<string[]>(['east', 'sh']); // 级联选择路径（外部受控演示）
 const splitSizes = signal<number[]>([35, 65]); // 分栏比例（外部受控演示）
+const acValue = signal(''); // 自动补全输入值（外部受控演示）
 const treePick = signal('core'); // 树形选中节点 key
 const transferKeys = signal<string[]>(['a11y']); // 穿梭框右侧集合（外部受控演示）
 const cityPick = signal(''); // 可搜索下拉的选中城市
@@ -681,6 +683,31 @@ const content = h(
       button({ label: '错误（可关）', variant: 'danger', onClick: () => notification({ title: '保存失败', description: '服务端返回 500，请稍后重试', variant: 'danger' }) }),
     ),
   ),
+  section(
+    'sec-autocomplete',
+    '自动补全',
+    'autoComplete：输入即过滤候选，↑↓ 环形高亮 / Enter 选中 / Esc 收起；options 传函数可做远程联想，空结果给提示行。',
+    h(
+      'div',
+      { class: 'row' },
+      autoComplete({
+        value: acValue,
+        placeholder: '输入组件名，如 table',
+        emptyText: '没有匹配的组件',
+        onSelect: (o) => toast.success(`已选 ${o.value}`),
+        options: [
+          { value: 'dataTable', hint: '表格' },
+          { value: 'transfer', hint: '穿梭框' },
+          { value: 'cascader', hint: '级联' },
+          { value: 'splitter', hint: '分栏' },
+          { value: 'autoComplete', hint: '联想' },
+          { value: 'pagination', hint: '分页' },
+        ],
+      }),
+      autoComplete({ placeholder: '按关键字动态算候选', options: (q) => [{ value: `${q}-alpha` }, { value: `${q}-beta` }] }),
+      h('span', { class: 'out' }, () => (acValue() ? `输入框当前值：${acValue()}` : '未输入')),
+    ),
+  ),
   section(
     'sec-splitter',
     '可拖拽分栏',

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T04:11:34.965Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T04:12:36.698Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -1255,6 +1255,35 @@ splitter({ sizes: ratio, min: 15, panes: [leftPanel, rightPanel], onChange: (s)
 
 现场演示：apps/docs/demo.html#sec-splitter
 
+### autoComplete — 自动补全 AutoComplete
+
+参数：
+
+- options（必填）：AutoCompleteOption[] | ((q: string) => AutoCompleteOption[]) —— 候选项：静态列表或按关键字计算的函数（可远程联想）
+- value：Signal<string> —— 输入值信号；不传则内部维护，传了即外部受控
+- placeholder：string —— 占位文案，同时作为无障碍名称
+- emptyText：string —— 无匹配时的提示文案；缺省「无匹配项」
+- maxItems：number —— 最多展示条数；缺省 8
+- disabled：boolean | Signal<boolean> —— 禁用输入与弹层
+- onInput：(query: string) => void —— 每次输入回调，适合触发远程请求
+- onSelect：(option: AutoCompleteOption) => void —— 选中回调（点击或 Enter）
+
+示例：
+
+```
+autoComplete({ value: acValue, placeholder: '输入组件名', options: [{ value: 'dataTable', hint: '表格' }], onSelect: (o) => toast.success(o.value) })
+```
+
+手把手：
+
+1. 输入任何字符即按包含匹配（忽略大小写）过滤候选，空串时弹层不展开
+2. ↑↓ 在候选间环形移动并高亮，Enter 选中，Esc 收起，Tab 失焦也会收起
+3. 候选行支持右侧 hint（分类 / 拼音），选中后值写回输入框并触发 onSelect
+4. options 传函数时每次输入都会用当前关键字调用，可在此发起远程请求并返回新数组
+5. value 传信号即受控：外部写入会同步回填输入框内容
+
+现场演示：apps/docs/demo.html#sec-autocomplete
+
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
@@ -1306,6 +1335,7 @@ API 速览：
 - transfer(props)：穿梭框，左右两栏勾选后整体搬运，targetKeys 信号双向绑定，两栏各自搜索与全选（含半选），禁用条目不参与搬运也不可勾选
 - cascader(props)：级联选择，多列联动面板（悬停下钻 / 点击提交），value 为路径数组信号，changeOnSelect 允许停在中间层，全键盘可操作
 - splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号
+- autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想
 
 一行用法：
 

llms.txt

@@ -96,6 +96,7 @@
   - transfer(props)：穿梭框，左右两栏勾选后整体搬运，targetKeys 信号双向绑定，两栏各自搜索与全选（含半选），禁用条目不参与搬运也不可勾选
   - cascader(props)：级联选择，多列联动面板（悬停下钻 / 点击提交），value 为路径数组信号，changeOnSelect 允许停在中间层，全键盘可操作
   - splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号
+  - autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想
 - 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')`
 - 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号
 - 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调

packages/skin/ui/src/autoComplete.ts

@@ -0,0 +1,116 @@
+import { effect, h, signal } from '@ui-arch/frame';
+import type { Signal } from '@ui-arch/frame';
+import { pushOverlay } from './overlay.js';
+import { flip } from './position.js';
+import type { AutoCompleteOption, AutoCompleteProps } from './types.js';
+
+let seq = 0; // 实例序号：给弹层列表一个稳定 id，供 aria-controls 关联
+
+/*** 自动补全：输入即过滤候选项，↑↓ 高亮 / Enter 选中 / Esc 收起，value 信号双向绑定 ***/ 
+export function autoComplete(props: AutoCompleteProps): HTMLElement {
+  // —— 状态集中声明 ——
+  const value: Signal<string> = props.value ?? signal(''); // 输入值
+  const open = signal(false);      // 弹层开合
+  const query = signal('');        // 当前过滤关键字（与 value 同步，独立信号便于受控写入）
+  const active = signal(-1);       // 键盘高亮下标，-1 表示无高亮
+  const place = signal<'top' | 'bottom'>('bottom'); // 实际方位
+  let releaseEsc: (() => void) | null = null; // Esc 栈注销函数
+  const max = props.maxItems ?? 8;
+
+  /*** 按关键字取候选：函数式入参交给调用方计算（可远程联想），结果截断到 maxItems ***/
+  const candidates = (): AutoCompleteOption[] => {
+    const all = typeof props.options === 'function' ? props.options(query()) : props.options;
+    const q = query().trim().toLowerCase();
+    const hit = q ? all.filter((o) => o.value.toLowerCase().includes(q)) : all; // 包含匹配，大小写不敏感
+    return hit.slice(0, max);
+  };
+
+  const input = h('input', {
+    type: 'text',
+    class: 'ua-autocomplete-input',
+    placeholder: props.placeholder ?? '',
+    'aria-label': props.placeholder ?? '自动补全',
+    role: 'combobox',
+    'aria-expanded': () => String(open()),
+    'aria-autocomplete': 'list',
+    disabled: props.disabled,
+    value: () => value(), // 外部写入信号时回填输入框
+    oninput: (e: Event) => {
+      const v = (e.target as HTMLInputElement).value;
+      value(v);
+      query(v);
+      active(-1);
+      open(v.trim().length > 0); // 空串收起，避免开屏就弹
+      props.onInput?.(v);
+    },
+  }) as HTMLInputElement;
+
+  const list = h('ul', { class: 'ua-autocomplete-list', role: 'listbox', id: `ua-ac-${(seq += 1)}` }) as HTMLElement;
+  input.setAttribute('aria-controls', list.id);
+  const pop = h('div', { class: () => `ua-autocomplete-pop${open() ? ' ua-open' : ''}${place() === 'top' ? ' is-flip' : ''}` }, list) as HTMLElement;
+  const root = h('div', { class: 'ua-autocomplete' }, input, pop) as HTMLElement;
+
+  /*** 选中候选：写值 + 收起 + 回调，焦点回到输入框便于继续输入 ***/
+  const pick = (opt: AutoCompleteOption): void => {
+    value(opt.value);
+    query(opt.value);
+    open(false);
+    active(-1);
+    props.onSelect?.(opt);
+    input.focus();
+  };
+
+  /*** 重绘候选行：高亮项由 active 决定，空结果渲染提示行 ***/
+  const render = (): void => {
+    const opts = candidates();
+    if (!opts.length) {
+      list.replaceChildren(h('li', { class: 'ua-autocomplete-empty' }, props.emptyText ?? '无匹配项'));
+      input.removeAttribute('aria-activedescendant');
+      return;
+    }
+    const rows = opts.map((opt, i) => {
+      const row = h(
+        'li',
+        {
+          class: () => `ua-autocomplete-opt${active() === i ? ' is-active' : ''}`,
+          role: 'option',
+          id: `${list.id}-${i}`,
+          'aria-selected': String(active() === i),
+          onmousedown: (e: Event) => { e.preventDefault(); pick(opt); }, // 阻止默认：保住输入框焦点，blur 后仍能选中
+        },
+        h('span', { class: 'ua-autocomplete-value' }, opt.value),
+        opt.hint ? h('span', { class: 'ua-autocomplete-hint' }, opt.hint) : null,
+      );
+      return row;
+    });
+    list.replaceChildren(...rows);
+    const cur = rows[active()];
+    if (cur) input.setAttribute('aria-activedescendant', cur.id); // 读屏跟随高亮
+    else input.removeAttribute('aria-activedescendant');
+  };
+
+  root.addEventListener('keydown', (e: KeyboardEvent) => {
+    const opts = candidates();
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+      e.preventDefault(); // 阻止光标跳行
+      if (!open() && opts.length) { open(true); active(0); return; } // 未展开：先展开并高亮首项
+      const dir = e.key === 'ArrowDown' ? 1 : -1;
+      active((active() + dir + opts.length) % opts.length); // 环形移动
+      return;
+    }
+    if (e.key === 'Enter' && open() && active() >= 0) { e.preventDefault(); pick(opts[active()]); return; } // 有高亮才回车选中
+    if (e.key === 'Tab') { open(false); return; } // 失焦前收起，避免残留浮层
+  });
+
+  document.addEventListener('click', (e) => {
+    if (root.contains(e.target as Node)) return; // 卫语句：组件内点击不处理
+    open(false);
+  });
+  effect(render); // 依赖 query / active / options，任一变化即重绘
+  effect(() => {
+    if (open()) releaseEsc ??= pushOverlay(() => { open(false); input.focus(); }); // 入栈逐层关闭
+    else { releaseEsc?.(); releaseEsc = null; }
+  });
+  effect(() => { if (open()) place(flip(input, pop, 'bottom')); }); // 空间不足自动翻转
+  return root;
+}

packages/skin/ui/src/index.ts

@@ -47,3 +47,4 @@ export { dataTable } from './dataTable.js';
 export { transfer } from './transfer.js';
 export { cascader } from './cascader.js';
 export { splitter } from './splitter.js';
+export { autoComplete } from './autoComplete.js';

packages/skin/ui/src/types.ts

@@ -523,4 +523,22 @@ export interface SplitterProps {
   onChange?: (sizes: number[]) => void; // 拖拽/键盘调整后回调（传副本）
 }
 
+/*** 自动补全候选 ***/
+export interface AutoCompleteOption {
+  value: string;   // 选中后写入输入框的值
+  hint?: string;   // 右侧补充说明（如分类 / 拼音）；缺省不渲染
+}
+
+/*** 自动补全入参 ***/
+export interface AutoCompleteProps {
+  options: AutoCompleteOption[] | ((query: string) => AutoCompleteOption[]); // 候选：静态列表或按关键字计算
+  value?: Signal<string>;                 // 输入值信号；不传则内部维护
+  placeholder?: string;                   // 占位文案
+  emptyText?: string;                     // 无匹配提示；缺省「无匹配项」
+  maxItems?: number;                      // 最多展示条数；缺省 8
+  disabled?: boolean | Signal<boolean>;   // 禁用输入与弹层
+  onInput?: (query: string) => void;      // 每次输入回调（可用于远程联想）
+  onSelect?: (option: AutoCompleteOption) => void; // 选中回调（点击或 Enter）
+}
+
 export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方

packages/skin/ui/ua.manifest.json

@@ -61,7 +61,8 @@
       "result(props)：结果页，status 四档语义色 + 标题 + 说明 + 操作区，用于提交完成/校验失败等终态",
       "transfer(props)：穿梭框，左右两栏勾选后整体搬运，targetKeys 信号双向绑定，两栏各自搜索与全选（含半选），禁用条目不参与搬运也不可勾选",
       "cascader(props)：级联选择，多列联动面板（悬停下钻 / 点击提交），value 为路径数组信号，changeOnSelect 允许停在中间层，全键盘可操作",
-      "splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号"
+      "splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号",
+      "autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -2066,6 +2067,62 @@
           "direction 传 vertical 变为上下分栏，键盘方向键与光标同步切换",
           "传入 sizes 信号即受控，外部写入可做「预设布局」切换（如 1:1 / 2:1）"
         ]
+      },
+      {
+        "id": "autoComplete",
+        "title": "自动补全 AutoComplete",
+        "demo": "sec-autocomplete",
+        "props": [
+          {
+            "n": "options",
+            "t": "AutoCompleteOption[] | ((q: string) => AutoCompleteOption[])",
+            "r": 1,
+            "d": "候选项：静态列表或按关键字计算的函数（可远程联想）"
+          },
+          {
+            "n": "value",
+            "t": "Signal<string>",
+            "d": "输入值信号；不传则内部维护，传了即外部受控"
+          },
+          {
+            "n": "placeholder",
+            "t": "string",
+            "d": "占位文案，同时作为无障碍名称"
+          },
+          {
+            "n": "emptyText",
+            "t": "string",
+            "d": "无匹配时的提示文案；缺省「无匹配项」"
+          },
+          {
+            "n": "maxItems",
+            "t": "number",
+            "d": "最多展示条数；缺省 8"
+          },
+          {
+            "n": "disabled",
+            "t": "boolean | Signal<boolean>",
+            "d": "禁用输入与弹层"
+          },
+          {
+            "n": "onInput",
+            "t": "(query: string) => void",
+            "d": "每次输入回调，适合触发远程请求"
+          },
+          {
+            "n": "onSelect",
+            "t": "(option: AutoCompleteOption) => void",
+            "d": "选中回调（点击或 Enter）"
+          }
+        ],
+        "example": "autoComplete({ value: acValue, placeholder: '输入组件名', options: [{ value: 'dataTable', hint: '表格' }], onSelect: (o) => toast.success(o.value) })",
+        "steps": [
+          "输入任何字符即按包含匹配（忽略大小写）过滤候选，空串时弹层不展开",
+          "↑↓ 在候选间环形移动并高亮，Enter 选中，Esc 收起，Tab 失焦也会收起",
+          "候选行支持右侧 hint（分类 / 拼音），选中后值写回输入框并触发 onSelect",
+          "options 传函数时每次输入都会用当前关键字调用，可在此发起远程请求并返回新数组",
+          "value 传信号即受控：外部写入会同步回填输入框内容"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -2721,3 +2721,91 @@ button.ua-step-dot:hover {
     transition: none;
   }
 }
+.ua-autocomplete {
+  position: relative;
+  display: inline-block;
+  width: 100%;
+  max-width: 320px;
+}
+.ua-autocomplete-input {
+  width: 100%;
+  padding: 8px var(--ua-space-2);
+  font-size: var(--ua-font-size-sm);
+  color: var(--ua-color-text);
+  background: var(--ua-color-surface);
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-sm);
+  outline: none;
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+.ua-autocomplete-input:focus {
+  border-color: var(--ua-color-accent);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--ua-color-accent) 18%, transparent);
+}
+.ua-autocomplete-input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.ua-autocomplete-pop {
+  position: absolute;
+  z-index: 40;
+  left: 0;
+  right: 0;
+  display: none;
+  margin-top: 4px;
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-md);
+  background: var(--ua-color-surface);
+  box-shadow: 0 12px 28px rgba(0, 0, 0, 0.18);
+  overflow: hidden;
+}
+.ua-autocomplete-pop.ua-open {
+  display: block;
+  animation: ua-ac-in 0.15s ease both;
+}
+.ua-autocomplete-pop.is-flip {
+  margin-top: 0;
+  margin-bottom: 4px;
+}
+.ua-autocomplete-list {
+  max-height: 220px;
+  margin: 0;
+  padding: var(--ua-space-1);
+  overflow: auto;
+  list-style: none;
+}
+.ua-autocomplete-opt {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--ua-space-1);
+  padding: 6px var(--ua-space-1);
+  border-radius: var(--ua-radius-sm);
+  font-size: var(--ua-font-size-sm);
+  color: var(--ua-color-text);
+  cursor: pointer;
+  transition: background 0.15s ease;
+}
+.ua-autocomplete-opt.is-active,
+.ua-autocomplete-opt:hover {
+  background: color-mix(in srgb, var(--ua-color-accent) 10%, transparent);
+}
+.ua-autocomplete-hint {
+  font-size: var(--ua-font-size-sm);
+  color: var(--ua-color-text-muted);
+}
+.ua-autocomplete-empty {
+  padding: var(--ua-space-2) 0;
+  text-align: center;
+  font-size: var(--ua-font-size-sm);
+  color: var(--ua-color-text-muted);
+}
+@keyframes ua-ac-in {
+  from { opacity: 0; transform: translateY(-4px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .ua-autocomplete-pop.ua-open { animation: none; }
+  .ua-autocomplete-input,
+  .ua-autocomplete-opt { transition: none; }
+}