iter(g144): 新增头像组组件 avatarGroup

packages/skin/ui/src/avatarGroup.ts

@@ -0,0 +1,22 @@
+import { h } from '@ui-arch/frame';
+import { avatar } from './avatar.js';
+import type { AvatarGroupProps } from './types.js';
+
+/*** 头像组：横向叠放（负边距 + 底色描边切口），超出 max 折叠成 +N，整组 title 列出全部姓名 ***/
+export function avatarGroup(props: AvatarGroupProps): HTMLElement {
+  const size = props.size ?? 32;             // 直径与单个 avatar 一致
+  const max = Math.max(props.max ?? 4, 1);   // 至少留一个位置，避免传 0 后只剩 +N
+  const shown = props.items.slice(0, max);   // 展示前 max 个
+  const rest = props.items.length - shown.length;
+  const group = h('div', {
+    class: 'ua-avatar-group',
+    title: props.items.map((item) => item.name).join('、'), // 折叠后仍能看到全部成员
+  }, ...shown.map((item) => avatar({ name: item.name, src: item.src, variant: item.variant, size })));
+  if (rest <= 0) return group; // 卫语句：没超上限就不渲染 +N
+  group.append(h('span', {
+    class: 'ua-avatar ua-avatar-more',
+    style: `width:${size}px;height:${size}px;font-size:${Math.round(size * 0.38)}px`,
+    'aria-label': `还有 ${rest} 人`, // 纯文本 +N 读屏会念成「加 3」，补可访问名
+  }, `+${rest}`));
+  return group;
+}

packages/skin/ui/src/index.ts

@@ -66,3 +66,4 @@ export { floatButton } from './floatButton.js';
 export { mentions } from './mentions.js';
 export { treeSelect } from './treeSelect.js';
 export { link } from './link.js';
+export { avatarGroup } from './avatarGroup.js';

packages/skin/ui/src/types.ts

@@ -827,4 +827,18 @@ export interface LinkProps {
   onClick?: (e: Event) => void; // 点击回调（禁用时不触发）
 }
 
+/*** 头像组成员项 ***/
+export interface AvatarItem {
+  name: string;                                            // 姓名：占位首字与悬停标题都用它
+  src?: string;                                            // 头像图片地址；缺省首字占位
+  variant?: 'default' | 'success' | 'warning' | 'danger';  // 首字底色语义档；缺省 default
+}
+
+/*** 头像组入参 ***/
+export interface AvatarGroupProps {
+  items: AvatarItem[]; // 成员列表，按显示顺序排列
+  max?: number;        // 最多展示几个，超出折叠成 +N；缺省 4
+  size?: number;       // 头像直径像素；缺省 32
+}
+
 export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方

packages/skin/ui/ua.manifest.json

@@ -80,7 +80,8 @@
       "floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label",
       "mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value",
       "treeSelect(props)：树形选择，按钮触发弹层并复用 tree（搜索 / 多选 / 级联），单选选中即收起、多选保持展开，Esc 与点外收起",
-      "link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报"
+      "link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报",
+      "avatarGroup(props)：头像组，横向叠放并在超出 max 时折叠成 +N，整组 title 列出全部姓名"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -3363,6 +3364,39 @@
           "禁用态只是去掉 href 并保持 aria-disabled，不做视觉上的「像普通文字」处理——需要完全不可聚焦请在外层控制渲染",
           "纯样式的「看起来像链接」用 typography({ underline: true })，不要为了样式引入带 href 的 a 标签"
         ]
+      },
+      {
+        "id": "avatarGroup",
+        "title": "头像组 AvatarGroup",
+        "demo": "sec-avatar",
+        "props": [
+          {
+            "n": "items",
+            "t": "AvatarItem[]",
+            "r": 1,
+            "d": "成员列表：每项含 name（姓名）、src（图片地址）、variant（首字底色语义档）"
+          },
+          {
+            "n": "max",
+            "t": "number",
+            "df": "4",
+            "d": "最多展示几个，超出折叠成 +N（至少展示 1 个）"
+          },
+          {
+            "n": "size",
+            "t": "number",
+            "df": "32",
+            "d": "头像直径像素，与 avatar 的 size 同义"
+          }
+        ],
+        "example": "avatarGroup({ items: [{ name: '张三' }, { name: '李四', variant: 'success' }, { name: '王五' }], max: 4 })",
+        "steps": [
+          "协作列表 / 评论头部展示参与人用它，比并排 avatar 省横向空间：叠放用负边距 + 底色描边切出入口",
+          "成员多时设 max：前 max 个照常显示，其余折叠成一个 +N，悬停任意头像都能看到全部姓名",
+          "只传 name 即首字占位，有图片就传 src；底色语义档用 variant（default / success / warning / danger）",
+          "整组是展示型元素：要有点击行为就在外面包 button 或 link，不要给单个头像加交互",
+          "size 与单个 avatar 一致，混排时把并排 avatar 与 avatarGroup 传同一个 size，视觉才对得上"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -4439,3 +4439,25 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
   gap: var(--ua-space-2);
   padding-bottom: var(--ua-space-1);
 }
+
+/* —— 头像组：负边距叠放，底色描边切出入口 —— */
+.ua-avatar-group {
+  display: inline-flex;
+  align-items: center;
+}
+.ua-avatar-group > .ua-avatar {
+  margin-left: calc(-1 * var(--ua-space-2));
+  box-shadow: 0 0 0 2px var(--ua-color-bg);
+}
+.ua-avatar-group > .ua-avatar:first-child {
+  margin-left: 0;
+}
+.ua-avatar-group > .ua-avatar:hover {
+  position: relative;
+  z-index: 1; /* 悬停的那个压在最上面，不被后一个盖住 */
+}
+.ua-avatar-more {
+  background: color-mix(in srgb, var(--ua-color-text-muted) 18%, transparent);
+  color: var(--ua-color-text);
+  font-weight: 500;
+}