@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/card/meta.md

@@ -0,0 +1,194 @@
+# Card
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+卡片 Card
+将相关内容和操作分组展示的容器，支持 Header/Title/Description/Action/Content/Footer/Media/Divider 子组件组合。
+
+## 使用场景
+
+- 展示信息摘要（统计数据、用户信息、任务卡片）
+- 作为表单或内容的包裹容器
+- 列表 / 网格布局中的单元
+- 整卡作为入口链接（asChild + interactive）
+- 数据加载中需要骨架屏占位（loading）
+- 折叠场景请改用 Accordion / Collapsible 与 Card 组合，不在 Card 内部内置。
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `variant` | `CardVariant` | `default` | – | 视觉风格。default 带细描边、elevated 带阴影、outlined 仅描边、ghost 无修饰。 |
+| `size` | `CardSize` | `default` | – | 尺寸：影响内边距与 gap。 |
+| `interactive` | `boolean` | `false` | – | 可交互态：hover 抬升 + cursor-pointer + focus ring，常配合 asChild 使用。 |
+| `asChild` | `boolean` | `false` | – | Slot 模式：将容器渲染为子元素（如 `<a>` / `<button>`），实现整卡链接。 |
+| `loading` | `boolean` | `false` | – | 加载状态：true 时容器内渲染骨架屏占位，外层 size/variant 仍生效。 |
+| `position` | `'top' \| 'bottom'` | `top` | – | 媒体位置：top 时清除卡片顶部内边距并启用顶部圆角，bottom 同理处理底部。 |
+| `asChild` | `boolean` | `false` | – | Slot 模式：将容器渲染为子元素（如 `<img>` / `<video>` 直接接管）。 |
+| `inset` | `boolean` | `false` | – | 分割线是否向内缩进，缩进后两侧留出与内边距等宽的留白。 |
+
+## 示例
+
+### Variants
+
+四种视觉风格：default / elevated / outlined / ghost。
+
+```tsx
+<div className="flex flex-wrap gap-4">
+  {(['default', 'elevated', 'outlined', 'ghost'] as const).map((v) => (
+    <Card key={v} variant={v} className="w-60">
+      <CardHeader>
+        <CardTitle>{v}</CardTitle>
+        <CardDescription>variant = {v}</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p className="text-muted-foreground">视觉风格演示。</p>
+      </CardContent>
+    </Card>
+  ))}
+</div>
+```
+
+### Sizes
+
+两档尺寸对比：default / sm。
+
+```tsx
+<div className="flex flex-wrap gap-4">
+  <Card size="default" className="w-60">
+    <CardHeader>
+      <CardTitle>Default</CardTitle>
+      <CardDescription>size = default</CardDescription>
+    </CardHeader>
+    <CardContent>
+      <p className="text-muted-foreground">标准内边距。</p>
+    </CardContent>
+  </Card>
+  <Card size="sm" className="w-60">
+    <CardHeader>
+      <CardTitle>Small</CardTitle>
+      <CardDescription>size = sm</CardDescription>
+    </CardHeader>
+    <CardContent>
+      <p className="text-muted-foreground">紧凑内边距。</p>
+    </CardContent>
+  </Card>
+</div>
+```
+
+### WithAction
+
+头部操作位：CardAction 自动定位到右上角。
+
+```tsx
+<Card className="w-80">
+  <CardHeader>
+    <CardTitle>通知</CardTitle>
+    <CardDescription>您有 3 条未读消息。</CardDescription>
+    <CardAction>
+      <Button variant="ghost" size="icon-sm">
+        <MoreHorizontalIcon />
+      </Button>
+    </CardAction>
+  </CardHeader>
+  <CardContent>
+    <p className="text-muted-foreground">点击查看详情。</p>
+  </CardContent>
+</Card>
+```
+
+### WithMedia
+
+媒体区：CardMedia 顶部展示图片。
+
+```tsx
+<Card className="w-80">
+  <CardMedia>
+    <img
+      src="https://picsum.photos/seed/teamix-card/640/240"
+      alt=""
+      className="h-40 object-cover"
+    />
+  </CardMedia>
+  <CardHeader>
+    <CardTitle>风景照</CardTitle>
+    <CardDescription>来自 picsum 的占位图。</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p className="text-muted-foreground">媒体区贴边，自动对齐圆角。</p>
+  </CardContent>
+</Card>
+```
+
+### WithDivider
+
+分割线：CardDivider 默认贯穿，inset 时两侧缩进。
+
+```tsx
+<Card className="w-80">
+  <CardHeader>
+    <CardTitle>账户信息</CardTitle>
+  </CardHeader>
+  <CardDivider />
+  <CardContent>
+    <p className="text-muted-foreground">用户名 / 邮箱 / 角色</p>
+  </CardContent>
+  <CardDivider inset />
+  <CardContent>
+    <p className="text-muted-foreground">上次登录：2 小时前</p>
+  </CardContent>
+</Card>
+```
+
+### Interactive
+
+整卡作为入口：interactive + asChild 让 Card 渲染为 `<a>`。
+
+```tsx
+<Card interactive asChild className="w-80">
+  <a href="#">
+    <CardHeader>
+      <CardTitle>查看文档</CardTitle>
+      <CardDescription>点击整张卡片即可跳转。</CardDescription>
+    </CardHeader>
+    <CardContent>
+      <p className="text-muted-foreground">配合 asChild 与原生链接语义。</p>
+    </CardContent>
+  </a>
+</Card>
+```
+
+### Loading
+
+加载态：loading=true 时容器内渲染骨架屏。
+
+```tsx
+<Card loading className="w-80">
+  <CardHeader>
+    <CardTitle>异步内容</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <p>真实内容</p>
+  </CardContent>
+</Card>
+```
+
+### CombineWithAccordion
+
+与 Accordion 组合：替代 cloud-design 的 CollapsableHead / CollapsableTail。
+
+```tsx
+<Card className="w-80 py-0">
+  <Accordion type="single" collapsible defaultValue="item-1">
+    <AccordionItem value="item-1" className="border-b-0">
+      <AccordionTrigger className="px-5 py-4">项目标题</AccordionTrigger>
+      <AccordionContent className="px-5 pb-5 text-xs">
+        折叠能力请用 Accordion / Collapsible 与 Card 组合，Card
+        自身不再内置。
+      </AccordionContent>
+    </AccordionItem>
+  </Accordion>
+</Card>
+```

package/src/components/card/stories.tsx

@@ -0,0 +1,202 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { MoreHorizontalIcon } from 'lucide-react';
+
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardAction,
+  CardContent,
+  CardFooter,
+  CardMedia,
+  CardDivider,
+} from './index';
+import { Button } from '@/components/button';
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from '@/components/accordion';
+
+const meta: Meta<typeof Card> = {
+  title: '数据展示 · Data Display/Card 卡片',
+  component: Card,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 基础卡片：标题 + 描述 + 内容 + 底部操作。 */
+export const Default: Story = {
+  render: () => (
+    <Card className="w-80">
+      <CardHeader>
+        <CardTitle>项目设置</CardTitle>
+        <CardDescription>管理您的项目配置和偏好。</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p className="text-muted-foreground">在此处配置部署与环境变量。</p>
+      </CardContent>
+      <CardFooter>
+        <Button>保存</Button>
+      </CardFooter>
+    </Card>
+  ),
+};
+
+/** 四种视觉风格：default / elevated / outlined / ghost。 */
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-wrap gap-4">
+      {(['default', 'elevated', 'outlined', 'ghost'] as const).map((v) => (
+        <Card key={v} variant={v} className="w-60">
+          <CardHeader>
+            <CardTitle>{v}</CardTitle>
+            <CardDescription>variant = {v}</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <p className="text-muted-foreground">视觉风格演示。</p>
+          </CardContent>
+        </Card>
+      ))}
+    </div>
+  ),
+};
+
+/** 两档尺寸对比：default / sm。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-wrap gap-4">
+      <Card size="default" className="w-60">
+        <CardHeader>
+          <CardTitle>Default</CardTitle>
+          <CardDescription>size = default</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <p className="text-muted-foreground">标准内边距。</p>
+        </CardContent>
+      </Card>
+      <Card size="sm" className="w-60">
+        <CardHeader>
+          <CardTitle>Small</CardTitle>
+          <CardDescription>size = sm</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <p className="text-muted-foreground">紧凑内边距。</p>
+        </CardContent>
+      </Card>
+    </div>
+  ),
+};
+
+/** 头部操作位：CardAction 自动定位到右上角。 */
+export const WithAction: Story = {
+  render: () => (
+    <Card className="w-80">
+      <CardHeader>
+        <CardTitle>通知</CardTitle>
+        <CardDescription>您有 3 条未读消息。</CardDescription>
+        <CardAction>
+          <Button variant="ghost" size="icon-sm">
+            <MoreHorizontalIcon />
+          </Button>
+        </CardAction>
+      </CardHeader>
+      <CardContent>
+        <p className="text-muted-foreground">点击查看详情。</p>
+      </CardContent>
+    </Card>
+  ),
+};
+
+/** 媒体区：CardMedia 顶部展示图片。 */
+export const WithMedia: Story = {
+  render: () => (
+    <Card className="w-80">
+      <CardMedia>
+        <img
+          src="https://picsum.photos/seed/teamix-card/640/240"
+          alt=""
+          className="h-40 object-cover"
+        />
+      </CardMedia>
+      <CardHeader>
+        <CardTitle>风景照</CardTitle>
+        <CardDescription>来自 picsum 的占位图。</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p className="text-muted-foreground">媒体区贴边，自动对齐圆角。</p>
+      </CardContent>
+    </Card>
+  ),
+};
+
+/** 分割线：CardDivider 默认贯穿，inset 时两侧缩进。 */
+export const WithDivider: Story = {
+  render: () => (
+    <Card className="w-80">
+      <CardHeader>
+        <CardTitle>账户信息</CardTitle>
+      </CardHeader>
+      <CardDivider />
+      <CardContent>
+        <p className="text-muted-foreground">用户名 / 邮箱 / 角色</p>
+      </CardContent>
+      <CardDivider inset />
+      <CardContent>
+        <p className="text-muted-foreground">上次登录：2 小时前</p>
+      </CardContent>
+    </Card>
+  ),
+};
+
+/** 整卡作为入口：interactive + asChild 让 Card 渲染为 `<a>`。 */
+export const Interactive: Story = {
+  render: () => (
+    <Card interactive asChild className="w-80">
+      <a href="#">
+        <CardHeader>
+          <CardTitle>查看文档</CardTitle>
+          <CardDescription>点击整张卡片即可跳转。</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <p className="text-muted-foreground">配合 asChild 与原生链接语义。</p>
+        </CardContent>
+      </a>
+    </Card>
+  ),
+};
+
+/** 加载态：loading=true 时容器内渲染骨架屏。 */
+export const Loading: Story = {
+  render: () => (
+    <Card loading className="w-80">
+      <CardHeader>
+        <CardTitle>异步内容</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <p>真实内容</p>
+      </CardContent>
+    </Card>
+  ),
+};
+
+/** 与 Accordion 组合：替代 cloud-design 的 CollapsableHead / CollapsableTail。 */
+export const CombineWithAccordion: Story = {
+  render: () => (
+    <Card className="w-80 py-0">
+      <Accordion type="single" collapsible defaultValue="item-1">
+        <AccordionItem value="item-1" className="border-b-0">
+          <AccordionTrigger className="px-5 py-4">项目标题</AccordionTrigger>
+          <AccordionContent className="px-5 pb-5 text-xs">
+            折叠能力请用 Accordion / Collapsible 与 Card 组合，Card
+            自身不再内置。
+          </AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    </Card>
+  ),
+};