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

packages/skin/ui/src/index.ts

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

packages/skin/ui/src/treeSelect.ts

@@ -0,0 +1,82 @@
+import { effect, h, signal } from '@ui-arch/frame';
+import { bindOutside, pushOverlay } from './overlay.js';
+import { tree } from './tree.js';
+import type { TreeNode, TreeSelectProps } from './types.js';
+
+/*** 按 key 深度优先找节点，用于把选中 key 还原成显示名 ***/
+function findNode(nodes: TreeNode[], key: string): TreeNode | null {
+  for (const node of nodes) {
+    if (node.key === key) return node; // 命中即返回
+    const hit = node.children ? findNode(node.children, key) : null;
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/*** 树形选择：按钮触发弹层，内部复用 tree（搜索 / 多选 / 级联由 tree 提供）；单选选中即收起，多选保持展开 ***/
+export function treeSelect(props: TreeSelectProps): HTMLElement {
+  const open = signal(false); // 弹层开合
+  const value = props.value ?? signal(''); // 单选 key
+  const checked = props.checked ?? signal<string[]>([]); // 多选 key 集合
+  let release: (() => void) | null = null; // Esc 栈注销句柄
+  const labelEl = h('span', { class: 'ua-treeselect-label' });
+  const trigger = h('button', {
+    class: 'ua-treeselect-trigger',
+    type: 'button',
+    'aria-haspopup': 'tree',
+    'aria-expanded': 'false',
+  }, labelEl, h('span', { class: 'ua-treeselect-arrow', 'aria-hidden': 'true' }, '▾')) as HTMLButtonElement;
+  const pop = h('div', { class: 'ua-treeselect-pop' });
+  const inner = tree({
+    nodes: props.nodes,
+    searchable: props.searchable,
+    multi: props.multi,
+    selected: value,
+    checked,
+    onSelect: (node) => {
+      if (!props.multi) close(); // 单选选中即收起，少一次点击
+      props.onSelect?.(node);
+    },
+    onCheck: (keys) => {
+      props.onChange?.(keys);
+    },
+  });
+  pop.append(inner);
+  const wrap = h('div', { class: 'ua-treeselect' }, trigger, pop);
+
+  /*** 收起弹层并注销 Esc 栈 ***/
+  function close(): void {
+    open(false);
+    release?.();
+    release = null;
+  }
+
+  /*** 触发器文案：单选回显节点名，多选回显已选数量，都没选则显示占位 ***/
+  const paint = (): void => {
+    const keys = checked();
+    if (props.multi) {
+      labelEl.textContent = keys.length ? `已选 ${keys.length} 项` : (props.placeholder ?? '请选择');
+    } else {
+      const node = value() ? findNode(props.nodes, value()) : null;
+      labelEl.textContent = node ? node.label : (props.placeholder ?? '请选择');
+    }
+    wrap.classList.toggle('is-empty', props.multi ? !keys.length : !value());
+    trigger.disabled = Boolean(props.disabled);
+  };
+
+  trigger.addEventListener('click', () => {
+    if (props.disabled) return; // 卫语句：禁用不响应
+    if (open()) return close();
+    open(true);
+    release = pushOverlay(close); // 与其他弹层共享 Esc 栈，只关最上层
+  });
+  bindOutside(wrap, open, close);
+  effect(() => {
+    const on = open();
+    wrap.classList.toggle('is-open', on);
+    trigger.setAttribute('aria-expanded', String(on));
+    if (on) inner.querySelector('input')?.focus(); // 展开即聚焦搜索框，键盘可直接用
+  });
+  effect(paint);
+  return wrap;
+}

packages/skin/ui/src/types.ts

@@ -795,4 +795,17 @@ export interface MentionsProps {
   onInput?: (text: string) => void;       // 每次输入的回调，参数为当前全文
 }
 
+/*** 树形选择入参 ***/
+export interface TreeSelectProps {
+  nodes: TreeNode[];                 // 根节点列表（结构同 tree）
+  value?: Signal<string>;            // 单选选中 key；不传则内部维护
+  checked?: Signal<string[]>;        // 多选勾选 key 集合（multi 时生效）；不传则内部维护
+  multi?: boolean;                   // 多选模式：显示勾选框、父子级联、选中不收起；缺省 false
+  searchable?: boolean;              // 弹层内带搜索框；缺省 false
+  placeholder?: string;              // 未选中时触发器文案；缺省「请选择」
+  disabled?: boolean;                // 禁用整个触发器；缺省 false
+  onSelect?: (node: TreeNode) => void;   // 单选选中回调（弹层已收起）
+  onChange?: (keys: string[]) => void;   // 多选勾选变更回调（传副本，父子已级联）
+}
+
 export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方

packages/skin/ui/ua.manifest.json

@@ -78,7 +78,8 @@
       "typography(props)：排版文本，variant 决定语义（标题出 h1-h5 / 段落出 p / 行内出 span），支持语义色、装饰位、对齐、多行截断与复制按钮",
       "grid(props, ...children)：栅格容器，columns 固定列数或 min 走 auto-fit 自适应列宽，gutter 统一列间距，窄屏自动降为单列",
       "floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label",
-      "mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value"
+      "mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value",
+      "treeSelect(props)：树形选择，按钮触发弹层并复用 tree（搜索 / 多选 / 级联），单选选中即收起、多选保持展开，Esc 与点外收起"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -3184,6 +3185,74 @@
           "弹层贴在输入框下沿而非跟随光标行（多行输入里更稳定，也不会被行高算错），需要跟随光标请自绘",
           "要限制可选人范围就在 items 上做过滤，组件不做远程搜索；远程场景用 onInput 拉数据后重建 items"
         ]
+      },
+      {
+        "id": "treeSelect",
+        "title": "树形选择 TreeSelect",
+        "demo": "sec-treeselect",
+        "props": [
+          {
+            "n": "nodes",
+            "t": "TreeNode[]",
+            "r": 1,
+            "d": "根节点列表，结构同 tree：key / label / children / disabled"
+          },
+          {
+            "n": "value",
+            "t": "Signal<string>",
+            "d": "单选选中 key；不传则内部维护"
+          },
+          {
+            "n": "checked",
+            "t": "Signal<string[]>",
+            "d": "多选勾选 key 集合（multi 时生效）；不传则内部维护"
+          },
+          {
+            "n": "multi",
+            "t": "boolean",
+            "df": "false",
+            "d": "多选模式：显示勾选框、父子级联、选中后弹层不收起"
+          },
+          {
+            "n": "searchable",
+            "t": "boolean",
+            "df": "false",
+            "d": "弹层内带搜索框（按标签过滤并保留父链）"
+          },
+          {
+            "n": "placeholder",
+            "t": "string",
+            "df": "请选择",
+            "d": "未选中时触发器文案"
+          },
+          {
+            "n": "disabled",
+            "t": "boolean",
+            "df": "false",
+            "d": "禁用整个触发器（不响应点击）"
+          },
+          {
+            "n": "onSelect",
+            "t": "(node: TreeNode) => void",
+            "k": 1,
+            "d": "单选选中回调（此时弹层已收起）"
+          },
+          {
+            "n": "onChange",
+            "t": "(keys: string[]) => void",
+            "k": 1,
+            "d": "多选勾选变更回调，传副本且父子已级联"
+          }
+        ],
+        "example": "const dept = signal(''); treeSelect({ nodes: [{ key: 'tech', label: '技术中心', children: [{ key: 'fe', label: '前端组' }] }], value: dept, searchable: true, onSelect: (n) => toast.info(n.label) })",
+        "steps": [
+          "表单里选层级归属（部门 / 分类 / 区域）用它，不要用 cascader——cascader 要求逐级选到叶子，treeSelect 允许选中间节点，也允许任意深度",
+          "单选默认选中即收起；要连续看结构就传 multi，勾选后弹层保持展开，触发器回显「已选 N 项」",
+          "需要在大树里找人/找分类就开 searchable：搜索按标签过滤并保留命中节点的父链，路径不会断",
+          "Esc 与其他弹层共享键盘栈（只关最上层），点外部也会收起；展开时焦点自动落到搜索框",
+          "选中值只存 key（单选 value / 多选 checked 数组），显示名由 nodes 反查——改 label 不需要迁移数据",
+          "禁用单个节点用 nodes 里的 disabled（该节点不可选，子节点仍可选）；禁用整个控件用 disabled"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -4228,3 +4228,83 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
     transition: none;
   }
 }
+
+/* —— 树形选择：触发器 + 下拉弹层，弹层内直接嵌入 tree —— */
+.ua-treeselect {
+  position: relative;
+  display: inline-block;
+  min-width: 220px;
+}
+.ua-treeselect-trigger {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--ua-space-2);
+  width: 100%;
+  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);
+  text-align: left;
+  cursor: pointer;
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+.ua-treeselect-trigger:hover {
+  border-color: color-mix(in srgb, var(--ua-color-accent) 55%, var(--ua-color-border));
+}
+.ua-treeselect-trigger:focus-visible,
+.ua-treeselect.is-open .ua-treeselect-trigger {
+  outline: none;
+  border-color: var(--ua-color-accent);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--ua-color-accent) 20%, transparent);
+}
+.ua-treeselect-trigger:disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+.ua-treeselect.is-empty .ua-treeselect-label {
+  color: var(--ua-color-text-muted);
+}
+.ua-treeselect-arrow {
+  color: var(--ua-color-text-muted);
+  font-size: 10px;
+  transition: transform 0.15s ease;
+}
+.ua-treeselect.is-open .ua-treeselect-arrow {
+  transform: rotate(180deg);
+}
+.ua-treeselect-pop {
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: calc(100% + 4px);
+  z-index: 30;
+  display: none;
+  max-height: 280px;
+  overflow: auto;
+  padding: var(--ua-space-2);
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-md);
+  background: var(--ua-color-surface);
+  box-shadow: 0 14px 30px color-mix(in srgb, var(--ua-color-text) 16%, transparent);
+}
+.ua-treeselect.is-open .ua-treeselect-pop {
+  display: block;
+  animation: ua-treeselect-in 0.15s ease;
+}
+@keyframes ua-treeselect-in {
+  from { opacity: 0; transform: translateY(-4px); }
+  to { opacity: 1; transform: none; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .ua-treeselect.is-open .ua-treeselect-pop {
+    animation: none;
+  }
+  .ua-treeselect-arrow,
+  .ua-treeselect-trigger {
+    transition: none;
+  }
+}