iter(g47): 新增 cascader 级联选择组件

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T04:07:52.893Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T04:10:00.644Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -1201,6 +1201,34 @@ transfer({ targetKeys: enabled, titles: ['待选', '已启用'], onChange: (keys
 
 现场演示：apps/docs/demo.html#sec-transfer
 
+### cascader — 级联选择 Cascader
+
+参数：
+
+- options（必填）：CascaderOption[] —— 根级选项，children 递归出列，value 逐级拼成路径
+- value：Signal<string[]> —— 选中路径信号；不传则内部维护，传了即外部受控
+- placeholder：string —— 未选时占位文案；缺省「请选择」
+- separator：string —— 路径分隔符；缺省「 / 」
+- changeOnSelect：boolean —— 允许停在中间层；缺省 false 必须选到叶子才提交
+- disabled：boolean | Signal<boolean> —— 禁用触发器；支持信号响应式禁用
+- onChange：(path: string[]) => void —— 选中回调（叶子或中间层，传副本）
+
+示例：
+
+```
+cascader({ value: areaPath, changeOnSelect: true, options: [{ value: 'east', label: '华东', children: [{ value: 'sh', label: '上海' }] }] })
+```
+
+手把手：
+
+1. 传入嵌套 options，第一列是根级选项，悬停带 children 的项即展开下一列
+2. 点击叶子提交；changeOnSelect 为 true 时点中间层也提交（适合「省/市」这类粗粒度就够用的场景）
+3. value 是路径数组（逐级 value），传信号即受控；触发器文案按 separator 拼接已提交路径
+4. 键盘：↑↓ 同列移动、→ 下钻、← 回退、Enter/空格 提交、Esc 收起（与弹窗共用一个 Esc 栈）
+5. 面板空间不足时自动向上翻转；disabled 选项不可点也不会展开下一列
+
+现场演示：apps/docs/demo.html#sec-cascader
+
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
@@ -1250,6 +1278,7 @@ API 速览：
 - notification(props)：右下角通知卡片（标题 + 描述 + 操作区），返回 { el, close } 句柄，缺省常驻需手动关闭
 - result(props)：结果页，status 四档语义色 + 标题 + 说明 + 操作区，用于提交完成/校验失败等终态
 - transfer(props)：穿梭框，左右两栏勾选后整体搬运，targetKeys 信号双向绑定，两栏各自搜索与全选（含半选），禁用条目不参与搬运也不可勾选
+- cascader(props)：级联选择，多列联动面板（悬停下钻 / 点击提交），value 为路径数组信号，changeOnSelect 允许停在中间层，全键盘可操作
 
 一行用法：