@teamix-evo/ui 0.4.0 → 0.5.2

package/src/components/item/meta.md

@@ -0,0 +1,363 @@
+# ItemGroup
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+列表项 Item
+通用列表项组件，支持多种尺寸、变体与布局模式，可组合图标、媒体、文本、操作区与附加信息。
+对齐 cloud-design List.Item + Antd v5 List.Item 能力集，按 shadcn v4 composable 理念实现。
+
+## 使用场景
+
+- 设置页的选项列表
+- 侧边栏菜单项
+- 数据列表的行项
+- 图文卡片（horizontal 布局）
+- 通知/消息列表
+- 带操作的资源列表
+- 组合结构：ItemGroup [bordered] [divider] > ItemGroupHeader + Item\* > ItemMedia + ItemContent (> ItemTitle + ItemDescription) + ItemExtra + ItemActions [separated] > ItemGroupFooter
+
+## Props
+
+| 名称        | 类型                                        | 默认值       | 必填 | 说明                         |
+| ----------- | ------------------------------------------- | ------------ | ---- | ---------------------------- |
+| `bordered`  | `"true" \| "false"`                         | –            | –    | –                            |
+| `divider`   | `"true" \| "false"`                         | –            | –    | –                            |
+| `variant`   | `"default" \| "outline" \| "muted"`         | `"default"`  | –    | –                            |
+| `size`      | `"default" \| "sm" \| "xs"`                 | `"default"`  | –    | –                            |
+| `layout`    | `"vertical" \| "horizontal"`                | `"vertical"` | –    | –                            |
+| `asChild`   | `boolean`                                   | –            | –    | 使用 Slot 模式渲染子元素     |
+| `variant`   | `"default" \| "icon" \| "image" \| "cover"` | `"default"`  | –    | –                            |
+| `separated` | `boolean`                                   | –            | –    | 子元素之间自动插入竖向分隔线 |
+
+## 示例
+
+### Variants
+
+变体对比
+
+```tsx
+<div className="flex flex-col gap-4">
+  <Item variant="default">
+    <ItemMedia variant="icon">
+      <FileIcon />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>Default 变体</ItemTitle>
+      <ItemDescription>无边框透明背景</ItemDescription>
+    </ItemContent>
+  </Item>
+  <Item variant="outline">
+    <ItemMedia variant="icon">
+      <FileIcon />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>Outline 变体</ItemTitle>
+      <ItemDescription>带边框</ItemDescription>
+    </ItemContent>
+  </Item>
+  <Item variant="muted">
+    <ItemMedia variant="icon">
+      <FileIcon />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>Muted 变体</ItemTitle>
+      <ItemDescription>浅背景</ItemDescription>
+    </ItemContent>
+  </Item>
+</div>
+```
+
+### Sizes
+
+尺寸对比
+
+```tsx
+<ItemGroup>
+  <Item size="default" variant="outline">
+    <ItemMedia variant="icon">
+      <FileIcon />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>Default 尺寸</ItemTitle>
+      <ItemDescription>标准间距</ItemDescription>
+    </ItemContent>
+  </Item>
+  <Item size="sm" variant="outline">
+    <ItemMedia variant="icon">
+      <FileIcon />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>Small 尺寸</ItemTitle>
+      <ItemDescription>紧凑间距</ItemDescription>
+    </ItemContent>
+  </Item>
+  <Item size="xs" variant="outline">
+    <ItemMedia variant="icon">
+      <FileIcon />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>XS 尺寸</ItemTitle>
+      <ItemDescription>极紧凑间距</ItemDescription>
+    </ItemContent>
+  </Item>
+</ItemGroup>
+```
+
+### Horizontal
+
+图文卡片布局
+
+```tsx
+<ItemGroup divider>
+  <Item layout="horizontal" variant="outline">
+    <ItemMedia variant="cover">
+      <img
+        src="https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=320&h=200&fit=crop"
+        alt="cover"
+      />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>构建一套产品化设计系统</ItemTitle>
+      <ItemDescription>
+        随着互联网行业的聚变式发展，在电商业务从"信息透出"到"在线交易"的过程中，网站
+        UI 构建也经历了多个阶段的演进。
+      </ItemDescription>
+      <span className="text-xs text-muted-foreground">3 小时前更新</span>
+    </ItemContent>
+    <ItemActions>
+      <Button size="sm" variant="link" className="text-muted-foreground">
+        编辑
+      </Button>
+      <Button size="sm" variant="link" className="text-muted-foreground">
+        删除
+      </Button>
+    </ItemActions>
+  </Item>
+  <Item layout="horizontal" variant="outline">
+    <ItemMedia variant="cover">
+      <img
+        src="https://images.unsplash.com/photo-1551650975-87deedd944c3?w=320&h=200&fit=crop"
+        alt="cover"
+      />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>移动端适配最佳实践</ItemTitle>
+      <ItemDescription>
+        响应式设计在现代 Web
+        开发中的关键角色，以及如何通过组件化方案解决多端适配问题。
+      </ItemDescription>
+      <span className="text-xs text-muted-foreground">1 天前更新</span>
+    </ItemContent>
+    <ItemActions>
+      <Button size="sm" variant="link" className="text-muted-foreground">
+        编辑
+      </Button>
+      <Button size="sm" variant="link" className="text-muted-foreground">
+        删除
+      </Button>
+    </ItemActions>
+  </Item>
+</ItemGroup>
+```
+
+### WithExtra
+
+右侧 Extra 信息
+
+```tsx
+<ItemGroup bordered divider>
+  <Item>
+    <ItemMedia variant="icon">
+      <StarIcon className="text-warning" />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>Pro 订阅</ItemTitle>
+      <ItemDescription>每月自动续费</ItemDescription>
+    </ItemContent>
+    <ItemExtra>$20/月</ItemExtra>
+  </Item>
+  <Item>
+    <ItemMedia variant="icon">
+      <BookmarkIcon className="text-primary" />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>Team 订阅</ItemTitle>
+      <ItemDescription>年付优惠</ItemDescription>
+    </ItemContent>
+    <ItemExtra>$180/年</ItemExtra>
+  </Item>
+</ItemGroup>
+```
+
+### ActionsSeparated
+
+Actions 自动分隔
+
+```tsx
+<Item variant="outline">
+  <ItemMedia variant="icon">
+    <FileIcon />
+  </ItemMedia>
+  <ItemContent>
+    <ItemTitle>资源文件</ItemTitle>
+    <ItemDescription>点击操作按钮管理</ItemDescription>
+  </ItemContent>
+  <ItemActions separated>
+    <Button size="sm" variant="link" className="text-muted-foreground">
+      <PencilIcon />
+      编辑
+    </Button>
+    <Button size="sm" variant="link" className="text-muted-foreground">
+      <BookmarkIcon />
+      收藏
+    </Button>
+    <Button
+      size="sm"
+      variant="link"
+      className="text-destructive hover:text-destructive/80"
+    >
+      <TrashIcon />
+      删除
+    </Button>
+  </ItemActions>
+</Item>
+```
+
+### GroupBordered
+
+带边框和分隔线的容器
+
+```tsx
+<ItemGroup bordered divider>
+  <Item>
+    <ItemMedia variant="icon">
+      <FileIcon />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>文档管理</ItemTitle>
+      <ItemDescription>管理所有项目文档</ItemDescription>
+    </ItemContent>
+  </Item>
+  <Item>
+    <ItemMedia variant="icon">
+      <ImageIcon />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>图片资源</ItemTitle>
+      <ItemDescription>管理图片和媒体文件</ItemDescription>
+    </ItemContent>
+  </Item>
+  <Item>
+    <ItemMedia variant="icon">
+      <StarIcon />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>收藏夹</ItemTitle>
+      <ItemDescription>查看已收藏的内容</ItemDescription>
+    </ItemContent>
+  </Item>
+</ItemGroup>
+```
+
+### GroupWithHeaderFooter
+
+带 Header 和 Footer 的列表
+
+```tsx
+<ItemGroup bordered divider>
+  <ItemGroupHeader>通知列表</ItemGroupHeader>
+  <Item>
+    <ItemMedia variant="icon">
+      <StarIcon className="text-warning" />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>新功能上线</ItemTitle>
+      <ItemDescription>系统已完成 v2.0 升级</ItemDescription>
+    </ItemContent>
+    <ItemExtra>2 小时前</ItemExtra>
+  </Item>
+  <Item>
+    <ItemMedia variant="icon">
+      <FileIcon />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>文档更新</ItemTitle>
+      <ItemDescription>API 文档已同步至最新版本</ItemDescription>
+    </ItemContent>
+    <ItemExtra>昨天</ItemExtra>
+  </Item>
+  <ItemGroupFooter>
+    <span>共 2 条通知</span>
+    <Button size="sm" variant="link" className="text-muted-foreground">
+      查看全部
+    </Button>
+  </ItemGroupFooter>
+</ItemGroup>
+```
+
+### WithHeaderFooter
+
+单 Item 内部 Header + Footer
+
+```tsx
+<Item variant="outline">
+  <ItemHeader>
+    <ItemTitle>任务标题</ItemTitle>
+    <Tag variant="status" status="processing">
+      进行中
+    </Tag>
+  </ItemHeader>
+  <ItemContent>
+    <ItemDescription>
+      这是一个较为复杂的列表项，包含头部和底部区域。
+    </ItemDescription>
+  </ItemContent>
+  <ItemFooter>
+    <span>截止：2025-01-15</span>
+    <Button size="sm" variant="link" className="text-muted-foreground">
+      查看
+    </Button>
+  </ItemFooter>
+</Item>
+```
+
+### ImageList
+
+图文列表（复刻 cloud-design complex）
+
+```tsx
+<ItemGroup divider>
+  <Item layout="horizontal">
+    <ItemMedia variant="image">
+      <img
+        src="https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=80&h=80&fit=crop"
+        alt="thumb"
+      />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>构建一套产品化设计系统</ItemTitle>
+      <ItemDescription>
+        随着互联网行业的聚变式发展，在电商业务从"信息透出"到"在线交易"的过程中…
+      </ItemDescription>
+    </ItemContent>
+    <ItemExtra>$20</ItemExtra>
+  </Item>
+  <Item layout="horizontal">
+    <ItemMedia variant="image">
+      <img
+        src="https://images.unsplash.com/photo-1551650975-87deedd944c3?w=80&h=80&fit=crop"
+        alt="thumb"
+      />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>移动端响应式方案</ItemTitle>
+      <ItemDescription>
+        响应式设计在现代 Web 开发中扮演着越来越重要的角色…
+      </ItemDescription>
+    </ItemContent>
+    <ItemExtra>$10</ItemExtra>
+  </Item>
+</ItemGroup>
+```