iter(g31): 新增 tree 树形组件

packages/skin/ui/src/index.ts

@@ -33,6 +33,7 @@ export { empty } from './empty.js';
 export { divider } from './divider.js';
 export { list } from './list.js';
 export { carousel } from './carousel.js';
+export { tree } from './tree.js';
 export { descriptions } from './descriptions.js';
 export { statistic } from './statistic.js';
 export { timeline } from './timeline.js';

packages/skin/ui/src/tree.ts

@@ -0,0 +1,98 @@
+import { effect, h, signal } from '@ui-arch/frame';
+import type { TreeProps, TreeNode } from './types.js';
+
+/*** 树形：递归渲染节点，箭头展开/收起，点击标签选中；键盘 Enter 选中、→ 展开、← 收起，被禁用的节点不响应 ***/
+export function tree(props: TreeProps): HTMLElement {
+  // —— 状态集中声明 ——
+  const expanded = props.expanded ?? signal<string[]>([]); // 展开的 key 集合，外部不传则内部维护
+  const selected = props.selected ?? signal(''); // 当前选中 key
+  const rows = new Map<string, HTMLElement>(); // key → 行元素，供响应式同步
+  const toggles = new Map<string, HTMLElement>(); // key → 展开箭头，供响应式同步
+
+  /*** 展开/收起一个节点（写回信号后由 effect 统一刷新 DOM） ***/
+  const toggle = (key: string) => {
+    const cur = expanded();
+    expanded(cur.includes(key) ? cur.filter((k) => k !== key) : [...cur, key]);
+  };
+
+  /*** 选中节点：写信号并回调 ***/
+  const pick = (node: TreeNode) => {
+    selected(node.key);
+    props.onSelect?.(node);
+  };
+
+  /*** 递归构建节点行：父行 + 子容器（子容器缩进一级） ***/
+  const build = (node: TreeNode, depth: number): HTMLElement => {
+    const on = expanded().includes(node.key);
+    const caret = h('span', { class: 'ua-tree-caret', 'aria-hidden': 'true' }, '›');
+    const row = h(
+      'div',
+      {
+        class: 'ua-tree-row',
+        role: 'treeitem',
+        'aria-level': String(depth + 1),
+        'aria-expanded': String(on),
+        tabindex: '0',
+        onClick: (e: Event) => {
+          if (node.disabled) return; // 卫语句：禁用节点不响应
+          if ((e.target as HTMLElement) === caret) toggle(node.key); // 点箭头只展开/收起
+          else pick(node);
+        },
+      },
+      caret,
+      h('span', { class: 'ua-tree-label' }, node.label),
+    );
+    rows.set(node.key, row);
+    toggles.set(node.key, caret);
+    if (!node.children?.length) caret.classList.add('ua-tree-caret-leaf'); // 叶子节点箭头置空位占位
+    const box = h('div', { class: 'ua-tree-children', role: 'group' }, ...(node.children ?? []).map((c) => build(c, depth + 1)));
+    return h('div', { class: 'ua-tree-node' }, row, box);
+  };
+
+  const root = h('div', { class: 'ua-tree', role: 'tree' }, ...props.nodes.map((n) => build(n, 0))) as HTMLElement;
+  if (props.defaultExpandAll) {
+    const all: string[] = [];
+    const walk = (list: TreeNode[]) => list.forEach((n) => { if (n.children?.length) { all.push(n.key); walk(n.children); } });
+    walk(props.nodes);
+    if (!expanded().length) expanded(all); // 仅在外部未给初值时展开全部
+  }
+
+  effect(() => {
+    const open = expanded();
+    const sel = selected();
+    for (const [key, row] of rows) {
+      const on = open.includes(key);
+      row.classList.toggle('ua-tree-open', on);
+      row.classList.toggle('ua-tree-selected', key === sel);
+      row.setAttribute('aria-selected', String(key === sel));
+      row.setAttribute('aria-expanded', String(on));
+      toggles.get(key)?.classList.toggle('ua-tree-caret-open', on); // 箭头随展开态旋转
+      const box = row.nextElementSibling as HTMLElement | null;
+      if (box) box.hidden = !on; // 收起即隐藏子容器
+    }
+  });
+
+  root.addEventListener('keydown', (e: KeyboardEvent) => {
+    const row = (e.target as HTMLElement).closest('.ua-tree-row') as HTMLElement | null;
+    if (!row) return; // 卫语句：焦点不在节点行
+    const key = [...rows.entries()].find(([, el]) => el === row)?.[0];
+    if (!key) return; // 卫语句：找不到对应节点
+    const node = findNode(props.nodes, key);
+    if (!node || node.disabled) return; // 卫语句：禁用节点不接管键盘
+    if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); pick(node); return; }
+    if (e.key === 'ArrowRight' && !expanded().includes(key)) { e.preventDefault(); toggle(key); return; } // → 展开
+    if (e.key === 'ArrowLeft' && expanded().includes(key)) { e.preventDefault(); toggle(key); } // ← 收起
+  });
+
+  return root;
+}
+
+/*** 按 key 深度查找节点（键盘操作需要拿到原始节点对象） ***/
+function findNode(nodes: TreeNode[], key: string): TreeNode | null {
+  for (const n of nodes) {
+    if (n.key === key) return n;
+    const hit = n.children ? findNode(n.children, key) : null;
+    if (hit) return hit;
+  }
+  return null;
+}

packages/skin/ui/src/types.ts

@@ -420,6 +420,23 @@ export interface ListProps {
   onItemClick?: (item: ListItem, index: number) => void; // 条目点击回调；提供后条目可点击并带 hover 反馈
 }
 
+/*** 树节点 ***/
+export interface TreeNode {
+  key: string;           // 唯一键（选中/展开都按 key 记）
+  label: string;         // 显示文案
+  children?: TreeNode[]; // 子节点；缺省为叶子
+  disabled?: boolean;    // 禁用：不可选中、不响应键盘
+}
+
+/*** 树形入参 ***/
+export interface TreeProps {
+  nodes: TreeNode[];                 // 根节点列表
+  expanded?: Signal<string[]>;       // 展开的 key 集合；不传则内部维护
+  selected?: Signal<string>;         // 选中 key 信号；不传则内部维护
+  defaultExpandAll?: boolean;        // 首屏展开全部分支；缺省 false
+  onSelect?: (node: TreeNode) => void; // 选中回调（点击或 Enter/空格）
+}
+
 /*** 轮播入参 ***/
 export interface CarouselProps {
   items: unknown[];        // 每张幻灯片内容，顺序即播放顺序

packages/skin/ui/ua.manifest.json

@@ -54,7 +54,8 @@
       "descriptions(props)：描述列表，items(label/value/span) 铺进 column 列网格，bordered 切表格形态，窄屏自动单列",
       "statistic(props)：统计数值，标题 + 大号数字 + 前后缀 + 环比趋势，value 变化时 rAF 滚动过渡（400ms easeOutCubic），减弱动效偏好下直落终值",
       "list(props)：列表，header/footer 外壳 + 条目 avatar/title/description/extra，onItemClick 让条目可点击，items 为空回落空状态",
-      "carousel(props)：轮播，items 横排位移，指示点/箭头/←→ 键切换，autoplay 毫秒自动前进且悬停暂停，index 信号可外部受控"
+      "carousel(props)：轮播，items 横排位移，指示点/箭头/←→ 键切换，autoplay 毫秒自动前进且悬停暂停，index 信号可外部受控",
+      "tree(props)：树形，递归节点 + 箭头展开/收起 + 点选节点，键盘 Enter 选中、→ 展开、← 收起，禁用节点不响应"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -1732,6 +1733,48 @@
           "键盘：聚焦轮播后 ←→ 切换，事件不冒泡避免连带切换外层 tabs/menu",
           "指示点与箭头都可点击，末张下一张环形回到首张"
         ]
+      },
+      {
+        "id": "tree",
+        "title": "树形 Tree",
+        "demo": "sec-tree",
+        "props": [
+          {
+            "n": "nodes",
+            "t": "TreeNode[]",
+            "r": 1,
+            "d": "根节点列表，每项 { key, label, children?, disabled? }"
+          },
+          {
+            "n": "expanded",
+            "t": "Signal<string[]>",
+            "d": "展开的 key 集合；不传则内部维护"
+          },
+          {
+            "n": "selected",
+            "t": "Signal<string>",
+            "d": "选中 key 信号；不传则内部维护"
+          },
+          {
+            "n": "defaultExpandAll",
+            "t": "boolean",
+            "d": "首屏展开全部分支；缺省 false"
+          },
+          {
+            "n": "onSelect",
+            "t": "(node: TreeNode) => void",
+            "k": 1,
+            "d": "选中回调：点击标签或 Enter/空格触发"
+          }
+        ],
+        "example": "const sel = signal(''); tree({ nodes: [{ key: 'src', label: 'src', children: [{ key: 'ui', label: 'ui' }] }], selected: sel, onSelect: (n) => console.log(n.key) })",
+        "steps": [
+          "节点树用 { key, label, children } 描述，key 唯一即可（选中与展开都按 key 记）",
+          "传 selected 信号即可外部受控；不传则组件内部维护选中态",
+          "点箭头只展开/收起，点标签才选中；叶子节点箭头位置留空以对齐",
+          "键盘 Enter/空格 选中、→ 展开、← 收起；disabled 节点点击与键盘都不响应",
+          "defaultExpandAll 首屏展开全部分支（外部已给 expanded 初值时以外部为准）"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -2142,3 +2142,56 @@ button.ua-step-dot:hover {
   .ua-carousel-dot,
   .ua-carousel-arrow { transition: none; }
 }
+
+/* —— 树形 —— */
+.ua-tree {
+  display: flex;
+  flex-direction: column;
+  font-size: var(--ua-font-size-md);
+}
+.ua-tree-row {
+  display: flex;
+  align-items: center;
+  gap: var(--ua-space-1);
+  padding: 4px var(--ua-space-2);
+  border-radius: var(--ua-radius-sm);
+  color: var(--ua-color-text);
+  cursor: pointer;
+  outline: none;
+  transition: background 0.15s ease;
+}
+.ua-tree-row:hover {
+  background: color-mix(in srgb, var(--ua-color-accent) 8%, transparent);
+}
+.ua-tree-row:focus-visible {
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--ua-color-accent) 40%, transparent);
+}
+.ua-tree-selected {
+  background: color-mix(in srgb, var(--ua-color-accent) 12%, transparent); /* 选中低视觉比重 */
+  font-weight: 600;
+}
+.ua-tree-caret {
+  display: inline-flex;
+  justify-content: center;
+  width: 14px;
+  color: var(--ua-color-text-muted);
+  transition: transform 0.15s ease;
+}
+.ua-tree-caret-open {
+  transform: rotate(90deg);
+}
+.ua-tree-caret-leaf {
+  visibility: hidden; /* 叶子节点留空位，标签对齐 */
+}
+.ua-tree-children {
+  padding-left: var(--ua-space-3);
+}
+.ua-tree-children[hidden] {
+  display: none;
+}
+@media (prefers-reduced-motion: reduce) {
+  .ua-tree-row,
+  .ua-tree-caret {
+    transition: none;
+  }
+}