iter(g133): 新增树形选择 treeSelect

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T07:22:32.759Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T07:24:00.739Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -1786,6 +1786,37 @@ const text = signal(''); mentions({ items: [{ name: 'zhangsan', label: '张三',
 
 现场演示：apps/docs/demo.html#sec-mentions
 
+### treeSelect — 树形选择 TreeSelect
+
+参数：
+
+- nodes（必填）：TreeNode[] —— 根节点列表，结构同 tree：key / label / children / disabled
+- value：Signal<string> —— 单选选中 key；不传则内部维护
+- checked：Signal<string[]> —— 多选勾选 key 集合（multi 时生效）；不传则内部维护
+- multi（默认 false）：boolean —— 多选模式：显示勾选框、父子级联、选中后弹层不收起
+- searchable（默认 false）：boolean —— 弹层内带搜索框（按标签过滤并保留父链）
+- placeholder（默认 请选择）：string —— 未选中时触发器文案
+- disabled（默认 false）：boolean —— 禁用整个触发器（不响应点击）
+- onSelect（回调）：(node: TreeNode) => void —— 单选选中回调（此时弹层已收起）
+- onChange（回调）：(keys: string[]) => void —— 多选勾选变更回调，传副本且父子已级联
+
+示例：
+
+```
+const dept = signal(''); treeSelect({ nodes: [{ key: 'tech', label: '技术中心', children: [{ key: 'fe', label: '前端组' }] }], value: dept, searchable: true, onSelect: (n) => toast.info(n.label) })
+```
+
+手把手：
+
+1. 表单里选层级归属（部门 / 分类 / 区域）用它，不要用 cascader——cascader 要求逐级选到叶子，treeSelect 允许选中间节点，也允许任意深度
+2. 单选默认选中即收起；要连续看结构就传 multi，勾选后弹层保持展开，触发器回显「已选 N 项」
+3. 需要在大树里找人/找分类就开 searchable：搜索按标签过滤并保留命中节点的父链，路径不会断
+4. Esc 与其他弹层共享键盘栈（只关最上层），点外部也会收起；展开时焦点自动落到搜索框
+5. 选中值只存 key（单选 value / 多选 checked 数组），显示名由 nodes 反查——改 label 不需要迁移数据
+6. 禁用单个节点用 nodes 里的 disabled（该节点不可选，子节点仍可选）；禁用整个控件用 disabled
+
+现场演示：apps/docs/demo.html#sec-treeselect
+
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
@@ -1854,6 +1885,7 @@ API 速览：
 - grid(props, ...children)：栅格容器，columns 固定列数或 min 走 auto-fit 自适应列宽，gutter 统一列间距，窄屏自动降为单列
 - floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label
 - mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value
+- treeSelect(props)：树形选择，按钮触发弹层并复用 tree（搜索 / 多选 / 级联），单选选中即收起、多选保持展开，Esc 与点外收起
 
 一行用法：