iter(g188): 新增命令面板组件

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T09:47:35.873Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T09:49:59.016Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -1952,6 +1952,34 @@ const vlist = virtualList({ items: users, itemHeight: 44, height: 320, renderIte
 
 现场演示：apps/docs/demo.html#sec-vlist
 
+### commandPalette — 命令面板 CommandPalette
+
+参数：
+
+- open（必填）：Signal<boolean> —— 显隐信号：外部写 true 唤起，组件内部关闭也会写回
+- items（必填）：CommandPaletteItem[] —— 全量命令，创建时快照；含 id / label / group / hint / keywords
+- placeholder：string —— 搜索框占位文案；缺省「搜索命令…」
+- emptyText：string —— 无匹配时的空状态文案；缺省「没有匹配的命令」
+- hotkey（默认 true）：boolean —— 是否注册 ⌘K / Ctrl+K 全局唤起；缺省 true，多实例场景可关掉自己绑
+- onSelect（必填）：(item) => void —— 回车或点击选中后回调：先收起并归还焦点，再回调
+
+示例：
+
+```
+const cmdk = commandPalette({ open: signal(false), items: [{ id: 'save', label: '保存当前页', group: '文件', hint: '⌘S' }, { id: 'invite', label: '邀请成员', group: '成员' }], onSelect: (it) => toast.info(`执行 ${it.label}`) }); document.body.append(cmdk.el); cmdk.open();
+```
+
+手把手：
+
+1. 把返回的 el 挂到 body（面板是 fixed + 遮罩，挂在 section 里也定位正确），之后用 open 信号或句柄 open()/close() 控制显隐
+2. items 是创建时快照：命令表变化（权限变化后菜单增减）请重建实例，不要直接改数组
+3. 过滤看 label / hint / keywords 三层：中文别名与拼音首字母塞进 keywords 即可支持，不必改组件
+4. 同组连续排列才合并成一段并画组标题；分组顺序按 items 顺序，组件不排序
+5. 键盘：↑↓ 环形选择、Home/End 跳首尾、回车执行、Esc 交给弹层栈（嵌套弹窗时只关最上层）；鼠标划过即高亮
+6. hotkey 缺省注册 ⌘K / Ctrl+K，同一页面多个面板请只留一个开 hotkey，其余传 hotkey: false
+
+现场演示：apps/docs/demo.html#sec-cmdk
+
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
@@ -2024,6 +2052,7 @@ API 速览：
 - link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报
 - avatarGroup(props)：头像组，横向叠放并在超出 max 时折叠成 +N，整组 title 列出全部姓名
 - virtualList(props)：虚拟列表，固定行高长列表只渲染可视窗口 + 上下缓冲条，万级数据滚动不随总量掉帧；返回 { el, scrollTo } 句柄
+- commandPalette(props)：命令面板，⌘K / Ctrl+K 唤起，输入即过滤（主文案/说明/关键词三层），↑↓ 环形选择 + 回车执行 + Esc 收起，选中与关闭都归还焦点；返回 { el, open, close } 句柄
 
 一行用法：