@teamix-evo/ui 0.1.1

package/src/components/card/card.stories.tsx

@@ -0,0 +1,112 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Heart, MessageSquare, MoreHorizontal, Share } from 'lucide-react';
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+  CardCover,
+  CardActions,
+  CardMeta,
+} from './card';
+import { Button } from '@/components/button/button';
+import {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+} from '@/components/avatar/avatar';
+
+const meta: Meta<typeof Card> = {
+  title: '布局与容器 · Layout/Card',
+  component: Card,
+  tags: ['autodocs'],
+  argTypes: {
+    hoverable: { control: 'boolean' },
+    loading: { control: 'boolean' },
+  },
+  args: { hoverable: false, loading: false },
+};
+
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+export const Basic: Story = {
+  render: (args) => (
+    <Card {...args} className="w-80">
+      <CardHeader
+        extra={
+          <Button size="icon" variant="ghost" aria-label="更多">
+            <MoreHorizontal />
+          </Button>
+        }
+      >
+        <CardTitle>项目名称</CardTitle>
+        <CardDescription>项目简介一行...</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p className="text-sm text-muted-foreground">主体内容区域。</p>
+      </CardContent>
+      <CardFooter className="justify-end gap-2">
+        <Button variant="outline">取消</Button>
+        <Button>确认</Button>
+      </CardFooter>
+    </Card>
+  ),
+};
+
+export const Hoverable: Story = {
+  args: { hoverable: true },
+  render: (args) => (
+    <Card {...args} className="w-72">
+      <CardContent className="pt-6">
+        <p className="text-sm">悬浮我看阴影变化</p>
+      </CardContent>
+    </Card>
+  ),
+};
+
+export const Loading: Story = {
+  args: { loading: true },
+  render: (args) => <Card {...args} className="w-80" />,
+};
+
+export const Media: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Card hoverable className="w-80">
+      <CardCover>
+        <img
+          src="https://placehold.co/600x320/e5e7eb/6b7280?text=Cover"
+          alt="cover"
+        />
+      </CardCover>
+      <CardContent className="pt-4">
+        <CardMeta
+          avatar={
+            <Avatar>
+              <AvatarImage src="https://github.com/shadcn.png" />
+              <AvatarFallback>U</AvatarFallback>
+            </Avatar>
+          }
+          title="发布者"
+          description="2 小时前 · 北京"
+        />
+      </CardContent>
+      <CardActions
+        items={[
+          <span key="like" className="inline-flex items-center gap-1">
+            <Heart className="size-4" /> 12
+          </span>,
+          <span key="share" className="inline-flex items-center gap-1">
+            <Share className="size-4" /> 4
+          </span>,
+          <span key="comment" className="inline-flex items-center gap-1">
+            <MessageSquare className="size-4" /> 8
+          </span>,
+        ]}
+      />
+    </Card>
+  ),
+};

package/src/components/card/card.tsx

@@ -0,0 +1,222 @@
+import * as React from 'react';
+
+import { cn } from '@/utils/cn';
+import { Skeleton } from '@/components/skeleton/skeleton';
+
+export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 鼠标 hover 时的视觉反馈(antd `hoverable` 并集) — 阴影升级 + 微交互。
+   * @default false
+   */
+  hoverable?: boolean;
+  /**
+   * 加载态(antd `loading` 并集) — 整卡渲染为骨架屏占位,不展示 children。
+   * @default false
+   */
+  loading?: boolean;
+}
+
+const Card = React.forwardRef<HTMLDivElement, CardProps>(
+  ({ className, hoverable = false, loading = false, children, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        'rounded-lg border bg-card text-card-foreground shadow-sm transition-shadow',
+        hoverable && 'cursor-pointer hover:shadow-md',
+        className,
+      )}
+      {...props}
+    >
+      {loading ? (
+        <div className="space-y-3 p-6">
+          <Skeleton shape="line" className="w-2/5" />
+          <Skeleton shape="line" />
+          <Skeleton shape="line" className="w-4/5" />
+        </div>
+      ) : (
+        children
+      )}
+    </div>
+  ),
+);
+Card.displayName = 'Card';
+
+export interface CardHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 右侧附加内容(antd `extra` 并集) — 用 flex 撑开,与 title/description 同行。
+   * 已等价 shadcn 2026-04 新增的 `CardAction` 子组件,推荐传 `<CardAction>...</CardAction>` 节点。
+   */
+  extra?: React.ReactNode;
+}
+
+const CardHeader = React.forwardRef<HTMLDivElement, CardHeaderProps>(
+  ({ className, extra, children, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn('flex flex-col space-y-1.5 p-6', className)}
+      {...props}
+    >
+      {extra ? (
+        <div className="flex items-start justify-between gap-3">
+          <div className="flex flex-1 flex-col space-y-1.5">{children}</div>
+          <div className="shrink-0">{extra}</div>
+        </div>
+      ) : (
+        children
+      )}
+    </div>
+  ),
+);
+CardHeader.displayName = 'CardHeader';
+
+const CardAction = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn(
+      'col-start-2 row-span-2 row-start-1 self-start justify-self-end',
+      className,
+    )}
+    {...props}
+  />
+));
+CardAction.displayName = 'CardAction';
+
+const CardTitle = React.forwardRef<
+  HTMLHeadingElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h3
+    ref={ref}
+    className={cn(
+      'text-base font-semibold leading-none tracking-tight',
+      className,
+    )}
+    {...props}
+  />
+));
+CardTitle.displayName = 'CardTitle';
+
+const CardDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    className={cn('text-sm text-muted-foreground', className)}
+    {...props}
+  />
+));
+CardDescription.displayName = 'CardDescription';
+
+const CardContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div ref={ref} className={cn('p-6 pt-0', className)} {...props} />
+));
+CardContent.displayName = 'CardContent';
+
+const CardFooter = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex items-center p-6 pt-0', className)}
+    {...props}
+  />
+));
+CardFooter.displayName = 'CardFooter';
+
+// ─── antd 风格 sub-components(并集)──────────────────────────────────────
+
+export interface CardCoverProps extends React.HTMLAttributes<HTMLDivElement> {}
+const CardCover = React.forwardRef<HTMLDivElement, CardCoverProps>(
+  ({ className, children, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        'overflow-hidden rounded-t-lg border-b [&>img]:w-full [&>img]:object-cover',
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  ),
+);
+CardCover.displayName = 'CardCover';
+
+export interface CardActionsProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** 操作项数组(antd `actions` 并集) — 自动均分等宽,中间分隔线。 */
+  items: React.ReactNode[];
+}
+const CardActions = React.forwardRef<HTMLDivElement, CardActionsProps>(
+  ({ className, items, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        'flex items-stretch divide-x divide-border border-t',
+        className,
+      )}
+      {...props}
+    >
+      {items.map((item, i) => (
+        <div
+          key={i}
+          className="flex flex-1 items-center justify-center py-3 text-sm text-muted-foreground transition-colors hover:bg-accent"
+        >
+          {item}
+        </div>
+      ))}
+    </div>
+  ),
+);
+CardActions.displayName = 'CardActions';
+
+export interface CardMetaProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+  /** 头像槽(antd `Card.Meta` `avatar` 并集)。 */
+  avatar?: React.ReactNode;
+  /** 标题(粗体)。 */
+  title?: React.ReactNode;
+  /** 描述。 */
+  description?: React.ReactNode;
+}
+const CardMeta = React.forwardRef<HTMLDivElement, CardMetaProps>(
+  ({ className, avatar, title, description, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn('flex items-start gap-3', className)}
+      {...props}
+    >
+      {avatar ? <div className="shrink-0">{avatar}</div> : null}
+      <div className="flex min-w-0 flex-1 flex-col gap-1">
+        {title ? (
+          <div className="text-sm font-semibold leading-none">{title}</div>
+        ) : null}
+        {description ? (
+          <div className="text-sm text-muted-foreground">{description}</div>
+        ) : null}
+      </div>
+    </div>
+  ),
+);
+CardMeta.displayName = 'CardMeta';
+
+export {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+  CardCover,
+  CardActions,
+  CardAction,
+  CardMeta,
+};

package/src/components/carousel/carousel.meta.md

@@ -0,0 +1,117 @@
+---
+id: carousel
+name: Carousel
+type: component
+category: data-display
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Carousel
+
+走马灯 — 基于 [`embla-carousel-react`](https://www.embla-carousel.com/),性能与可访问性出色。
+对应 antd `Carousel` 的核心场景。
+
+## When to use
+
+- 首屏 banner / 营销轮播
+- 卡片横向滚动(配 `basis-1/3` 等让一屏多卡可见)
+- 图片画廊
+- 商品 / 服务的横向展示
+
+## When NOT to use
+
+- 密集 tab 切换 → `Tabs`
+- 数据表格 → `Table` / `DataTable`
+- 全屏画廊(含缩放 / 全屏)→ 专用图库组件
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `opts` | `CarouselOptions` | – | – | embla 选项透传(`loop / align / startIndex / dragFree` 等)。 |
+| `plugins` | `CarouselPlugin` | – | – | embla 插件数组(`autoplay`、`fade` 等)。 |
+| `orientation` | `'horizontal' \| 'vertical'` | `"horizontal"` | – | 滚动方向。 |
+| `setApi` | `(api: CarouselApi) => void` | – | – | 提供 embla API 的回调,用于业务侧自行控制(scrollNext / scrollTo 等)。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add carousel` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add embla-carousel-react@^8.0.0 lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+> 子组件:`Carousel`(主容器,内置 embla)/ `CarouselContent`(可滚动 wrapper)/ `CarouselItem`(单页)/ `CarouselPrevious` + `CarouselNext`(导航按钮)+ `useCarousel()` 内部 hook。
+
+## AI 生成纪律
+
+- **`opts.loop` 默认 false**:必须显式开启 loop 才能循环
+- **配 `setApi` 拿 embla API**:业务侧需要 `scrollTo / on('select', ...)` 时,通过 `setApi` 回调收口
+- **`basis-*` 控制每屏几张**:`<CarouselItem className="basis-1/3">` 一屏 3 张
+- **`orientation="vertical"` 父容器需固定高度**:embla 不会自动撑开
+- **autoplay 用 `embla-carousel-autoplay` 插件**:`plugins={[Autoplay({ delay: 4000 })]}`
+- **触屏拖动自带**:不需要额外配置
+
+## Examples
+
+```tsx
+import {
+  Carousel, CarouselContent, CarouselItem,
+  CarouselPrevious, CarouselNext,
+} from '@/components/ui/carousel';
+
+// 基础(单页)
+<Carousel className="w-full max-w-md">
+  <CarouselContent>
+    {Array.from({ length: 5 }).map((_, i) => (
+      <CarouselItem key={i}>
+        <Card>{i + 1}</Card>
+      </CarouselItem>
+    ))}
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+
+// 一屏 3 张
+<Carousel opts={{ align: 'start' }} className="w-full max-w-2xl">
+  <CarouselContent>
+    {items.map((it, i) => (
+      <CarouselItem key={i} className="md:basis-1/3">
+        <Card>{it.title}</Card>
+      </CarouselItem>
+    ))}
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+
+// 受控 / 拿 API
+const [api, setApi] = React.useState<CarouselApi>();
+React.useEffect(() => {
+  if (!api) return;
+  api.on('select', () => console.log('current:', api.selectedScrollSnap()));
+}, [api]);
+
+<Carousel setApi={setApi}>...</Carousel>
+```

package/src/components/carousel/carousel.stories.tsx

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselPrevious,
+  CarouselNext,
+} from './carousel';
+import { Card, CardContent } from '@/components/card/card';
+
+const meta: Meta<typeof Carousel> = {
+  title: '数据展示 · Data Display/Carousel',
+  component: Carousel,
+  tags: ['autodocs'],
+  parameters: { layout: 'centered' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Carousel>;
+
+export const Single: Story = {
+  render: () => (
+    <Carousel className="w-full max-w-md">
+      <CarouselContent>
+        {Array.from({ length: 5 }).map((_, i) => (
+          <CarouselItem key={i}>
+            <Card>
+              <CardContent className="flex aspect-video items-center justify-center p-6">
+                <span className="text-4xl font-semibold">{i + 1}</span>
+              </CardContent>
+            </Card>
+          </CarouselItem>
+        ))}
+      </CarouselContent>
+      <CarouselPrevious />
+      <CarouselNext />
+    </Carousel>
+  ),
+};
+
+export const ThreePerView: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Carousel
+      opts={{ align: 'start' }}
+      className="w-full max-w-2xl"
+    >
+      <CarouselContent>
+        {Array.from({ length: 8 }).map((_, i) => (
+          <CarouselItem key={i} className="md:basis-1/3">
+            <Card>
+              <CardContent className="flex aspect-square items-center justify-center p-6">
+                <span className="text-3xl font-semibold">{i + 1}</span>
+              </CardContent>
+            </Card>
+          </CarouselItem>
+        ))}
+      </CarouselContent>
+      <CarouselPrevious />
+      <CarouselNext />
+    </Carousel>
+  ),
+};
+
+export const Looping: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Carousel className="w-full max-w-md" opts={{ loop: true }}>
+      <CarouselContent>
+        {Array.from({ length: 4 }).map((_, i) => (
+          <CarouselItem key={i}>
+            <Card>
+              <CardContent className="flex aspect-video items-center justify-center p-6">
+                <span className="text-2xl">循环 #{i + 1}</span>
+              </CardContent>
+            </Card>
+          </CarouselItem>
+        ))}
+      </CarouselContent>
+      <CarouselPrevious />
+      <CarouselNext />
+    </Carousel>
+  ),
+};