@ceed/ads 1.13.4 → 1.15.0-next.2

package/dist/components/surfaces/Card.md

@@ -0,0 +1,786 @@
+# Card
+
+## Introduction
+
+Card 컴포넌트는 관련된 내용과 액션을 하나의 컨테이너로 묶어서 표시하는 UI 요소입니다. 정보를 구조화하고 시각적으로 그룹화하여 사용자가 쉽게 스캔하고 이해할 수 있도록 도와줍니다. 뉴스피드, 제품 목록, 사용자 프로필, 대시보드 위젯 등 다양한 용도로 사용됩니다.
+
+```tsx
+<Card {...args} sx={{
+  maxWidth: 320
+}}>
+<CardContent>
+  <Typography level="title-md">Card Title</Typography>
+  <Typography level="body-sm">이것은 카드의 내용입니다. 여기에 다양한 정보를 표시할 수 있습니다.</Typography>
+</CardContent>
+</Card>
+```
+
+| Field   | Description | Default    |
+| ------- | ----------- | ---------- |
+| variant | 카드 스타일 변형   | "outlined" |
+| color   | 카드 색상       | "neutral"  |
+| size    | 카드 크기       | "md"       |
+
+## Usage
+
+```tsx
+import { Card, CardContent, CardActions, CardCover, CardOverflow } from '@ceed/ads';
+
+function MyComponent() {
+  return (
+    <Card sx={{ maxWidth: 320 }}>
+      <CardContent>
+        <Typography level="title-lg">카드 제목</Typography>
+        <Typography level="body-md">카드의 내용이 들어갑니다.</Typography>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+## Examples
+
+### Basic Usage
+
+가장 기본적인 카드 사용법입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Card sx={{
+  maxWidth: 300
+}}>
+<CardContent>
+  <Typography level="title-lg">기본 카드</Typography>
+  <Typography level="body-md">
+    이것은 가장 기본적인 카드 형태입니다. 제목과 내용으로 구성되어 있습니다.
+  </Typography>
+</CardContent>
+</Card>
+</div>
+```
+
+### Variants
+
+다양한 스타일 변형을 제공합니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Card variant="solid" sx={{
+  maxWidth: 300
+}}>
+<CardContent>
+  <Typography level="title-md">Solid</Typography>
+  <Typography level="body-sm">Solid 스타일 카드</Typography>
+</CardContent>
+</Card>
+
+<Card variant="soft" sx={{
+  maxWidth: 300
+}}>
+<CardContent>
+  <Typography level="title-md">Soft</Typography>
+  <Typography level="body-sm">Soft 스타일 카드</Typography>
+</CardContent>
+</Card>
+
+<Card variant="outlined" sx={{
+  maxWidth: 300
+}}>
+<CardContent>
+  <Typography level="title-md">Outlined</Typography>
+  <Typography level="body-sm">Outlined 스타일 카드</Typography>
+</CardContent>
+</Card>
+
+<Card variant="plain" sx={{
+  maxWidth: 300
+}}>
+<CardContent>
+  <Typography level="title-md">Plain</Typography>
+  <Typography level="body-sm">Plain 스타일 카드</Typography>
+</CardContent>
+</Card>
+</div>
+```
+
+### Colors
+
+다양한 색상을 적용할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Card color="primary" variant="soft" sx={{
+  maxWidth: 300
+}}>
+<CardContent>
+  <Typography level="title-md">Primary</Typography>
+  <Typography level="body-sm">Primary 색상 카드</Typography>
+</CardContent>
+</Card>
+
+<Card color="neutral" variant="soft" sx={{
+  maxWidth: 300
+}}>
+<CardContent>
+  <Typography level="title-md">Neutral</Typography>
+  <Typography level="body-sm">Neutral 색상 카드</Typography>
+</CardContent>
+</Card>
+
+<Card color="danger" variant="soft" sx={{
+  maxWidth: 300
+}}>
+<CardContent>
+  <Typography level="title-md">Danger</Typography>
+  <Typography level="body-sm">Danger 색상 카드</Typography>
+</CardContent>
+</Card>
+
+<Card color="success" variant="soft" sx={{
+  maxWidth: 300
+}}>
+<CardContent>
+  <Typography level="title-md">Success</Typography>
+  <Typography level="body-sm">Success 색상 카드</Typography>
+</CardContent>
+</Card>
+
+<Card color="warning" variant="soft" sx={{
+  maxWidth: 300
+}}>
+<CardContent>
+  <Typography level="title-md">Warning</Typography>
+  <Typography level="body-sm">Warning 색상 카드</Typography>
+</CardContent>
+</Card>
+</div>
+```
+
+### Sizes
+
+크기를 조절할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  alignItems: 'flex-start',
+  flexWrap: 'wrap'
+}}>
+<Card size="sm" sx={{
+  maxWidth: 250
+}}>
+<CardContent>
+  <Typography level="title-sm">Small</Typography>
+  <Typography level="body-xs">작은 크기의 카드입니다.</Typography>
+</CardContent>
+</Card>
+
+<Card size="md" sx={{
+  maxWidth: 300
+}}>
+<CardContent>
+  <Typography level="title-md">Medium</Typography>
+  <Typography level="body-sm">중간 크기의 카드입니다.</Typography>
+</CardContent>
+</Card>
+
+<Card size="lg" sx={{
+  maxWidth: 350
+}}>
+<CardContent>
+  <Typography level="title-lg">Large</Typography>
+  <Typography level="body-md">큰 크기의 카드입니다.</Typography>
+</CardContent>
+</Card>
+</div>
+```
+
+### With Cover
+
+이미지를 배경으로 사용할 수 있는 CardCover 컴포넌트를 활용한 카드입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Card sx={{
+  maxWidth: 320
+}}>
+<CardCover>
+  <img src="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=320" loading="lazy" alt="Night view" />
+</CardCover>
+<CardContent>
+  <Typography level="body-lg" textColor="#fff">
+    Beautiful Night View
+  </Typography>
+  <Typography level="body-sm" textColor="neutral.300">
+    A stunning cityscape at night
+  </Typography>
+</CardContent>
+</Card>
+
+<Card sx={{
+  maxWidth: 320
+}}>
+<CardCover>
+  <img src="https://images.unsplash.com/photo-1527549993586-dff825b37782?auto=format&fit=crop&w=320" loading="lazy" alt="Mountain" />
+</CardCover>
+<CardContent sx={{
+  justifyContent: 'flex-end'
+}}>
+<Typography level="title-lg" textColor="#fff">
+  Mountain Peak
+</Typography>
+<Typography level="body-sm" textColor="neutral.300">
+  Majestic mountain landscape
+</Typography>
+</CardContent>
+</Card>
+</div>
+```
+
+### With Actions
+
+하단에 액션 버튼들을 배치할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Card sx={{
+  maxWidth: 320
+}}>
+<CardContent>
+  <Typography level="title-lg">게시물</Typography>
+  <Typography level="body-md">
+    이것은 액션 버튼이 있는 카드입니다. 하단에 다양한 액션을 수행할 수 있는 버튼들이 있습니다.
+  </Typography>
+</CardContent>
+<CardActions>
+  <Button variant="soft" size="sm">
+    좋아요
+  </Button>
+  <Button variant="soft" size="sm">
+    공유하기
+  </Button>
+  <Button variant="soft" size="sm">
+    더보기
+  </Button>
+</CardActions>
+</Card>
+
+<Card sx={{
+  maxWidth: 320
+}}>
+<CardContent>
+  <Typography level="title-lg">설정</Typography>
+  <Typography level="body-md">설정을 변경하시겠습니까? 이 작업은 되돌릴 수 없습니다.</Typography>
+</CardContent>
+<CardActions buttonFlex={1}>
+  <Button variant="outlined" color="neutral">
+    취소
+  </Button>
+  <Button variant="solid" color="primary">
+    확인
+  </Button>
+</CardActions>
+</Card>
+</div>
+```
+
+### With Overflow
+
+CardOverflow를 사용하여 카드의 경계를 넘나드는 콘텐츠를 표시할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem',
+  flexWrap: 'wrap',
+  alignItems: 'flex-start'
+}}>
+{/* CardOverflow 비교 예제 */}
+<div>
+  <Typography level="body-sm" sx={{
+    mb: 2,
+    textAlign: 'center'
+  }}>
+  일반 Card (패딩 있음)
+</Typography>
+<Card variant="outlined" sx={{
+  maxWidth: 280
+}}>
+<CardContent sx={{
+  bgcolor: 'background.level1'
+}}>
+<img src="https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?auto=format&fit=crop&w=280" loading="lazy" alt="Profile" style={{
+  width: '100%',
+  height: 160,
+  objectFit: 'cover',
+  borderRadius: '4px'
+}} />
+</CardContent>
+<CardContent>
+  <Typography level="title-md">John Doe</Typography>
+  <Typography level="body-sm">Software Engineer</Typography>
+</CardContent>
+<CardActions>
+  <Button size="sm" variant="soft">
+    팔로우
+  </Button>
+  <Button size="sm" variant="solid">
+    메시지
+  </Button>
+</CardActions>
+</Card>
+</div>
+
+{/* CardOverflow 사용 예제 */}
+<div>
+  <Typography level="body-sm" sx={{
+    mb: 2,
+    textAlign: 'center'
+  }}>
+  CardOverflow 사용 (패딩 무시)
+</Typography>
+<Card variant="outlined" sx={{
+  maxWidth: 280
+}}>
+<CardOverflow>
+  <AspectRatio ratio="3/4">
+    <img src="https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?auto=format&fit=crop&w=280" loading="lazy" alt="Profile" />
+  </AspectRatio>
+</CardOverflow>
+<CardContent>
+  <Typography level="title-md">John Doe</Typography>
+  <Typography level="body-sm">Software Engineer</Typography>
+</CardContent>
+<CardOverflow variant="soft" sx={{
+  bgcolor: 'background.level1'
+}}>
+<CardActions sx={{
+  pt: 2,
+  pb: 2,
+  px: 2
+}} buttonFlex={1}>
+<Button size="sm" variant="soft">
+  팔로우
+</Button>
+<Button size="sm" variant="solid">
+  메시지
+</Button>
+</CardActions>
+</CardOverflow>
+</Card>
+</div>
+
+{/* 복합 CardOverflow 예제 */}
+<div>
+  <Typography level="body-sm" sx={{
+    mb: 2,
+    textAlign: 'center'
+  }}>
+  다양한 CardOverflow 활용
+</Typography>
+<Card variant="outlined" sx={{
+  maxWidth: 280
+}}>
+<CardOverflow>
+  <AspectRatio ratio="3">
+    <div style={{
+      background: 'linear-gradient(45deg, #2196F3 30%, #21CBF3 90%)',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      color: 'white'
+    }}>
+    <Typography level="title-lg" textColor="white">
+      HEADER OVERFLOW
+    </Typography>
+  </div>
+</AspectRatio>
+</CardOverflow>
+<CardContent sx={{
+  textAlign: 'center'
+}}>
+<Typography level="title-md">카드 제목</Typography>
+<Typography level="body-sm">
+  CardOverflow를 사용하면 카드의 패딩을 무시하고 전체 너비를 활용할 수 있습니다.
+</Typography>
+</CardContent>
+<CardOverflow variant="plain" sx={{
+  bgcolor: 'warning.50'
+}}>
+<Divider inset="context" />
+<CardContent sx={{
+  py: 1.5
+}}>
+<Typography level="body-xs" textAlign="center" color="warning">
+  ⚠️ 이 영역도 CardOverflow로 만들어졌습니다
+</Typography>
+</CardContent>
+</CardOverflow>
+</Card>
+</div>
+</div>
+```
+
+### Interactive Cards
+
+클릭 가능하고 호버 효과가 있는 인터랙티브한 카드들입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Card variant="outlined" sx={{
+  maxWidth: 320,
+  cursor: 'pointer',
+  '&:hover': {
+    boxShadow: 'md',
+    borderColor: 'primary.outlinedHoverBorder'
+  }
+}} onClick={() => alert('카드를 클릭했습니다!')}>
+<CardContent>
+  <Typography level="title-md">클릭 가능한 카드</Typography>
+  <Typography level="body-sm">이 카드를 클릭하면 액션이 실행됩니다. 호버 효과도 확인해보세요.</Typography>
+</CardContent>
+</Card>
+
+<Card variant="soft" color="primary" sx={{
+  maxWidth: 320,
+  cursor: 'pointer',
+  transition: 'transform 0.2s',
+  '&:hover': {
+    transform: 'translateY(-2px)'
+  }
+}}>
+<CardContent>
+  <Typography level="title-md">호버 애니메이션</Typography>
+  <Typography level="body-sm">마우스를 올리면 카드가 살짝 올라갑니다.</Typography>
+</CardContent>
+</Card>
+</div>
+```
+
+### Media Cards
+
+이미지와 함께 사용하는 미디어 카드들입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Card sx={{
+  maxWidth: 320
+}}>
+<CardOverflow>
+  <AspectRatio ratio="1">
+    <img src="https://images.unsplash.com/photo-1542291026-7eec264c27ff?auto=format&fit=crop&w=320" loading="lazy" alt="Shoes" />
+  </AspectRatio>
+</CardOverflow>
+<CardContent>
+  <Typography level="title-lg">운동화</Typography>
+  <Typography level="body-md">편안하고 스타일리시한 운동화입니다.</Typography>
+  <Typography level="title-lg" sx={{
+    color: 'primary.main'
+  }}>
+  ₩129,000
+</Typography>
+</CardContent>
+<CardActions>
+  <Button variant="solid" color="primary" fullWidth>
+    구매하기
+  </Button>
+</CardActions>
+</Card>
+
+<Card sx={{
+  maxWidth: 320
+}}>
+<CardOverflow>
+  <AspectRatio ratio="1">
+    <img src="https://images.unsplash.com/photo-1551963831-b3b1ca40c98e?auto=format&fit=crop&w=320" loading="lazy" alt="Breakfast" />
+  </AspectRatio>
+</CardOverflow>
+<CardContent>
+  <div style={{
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'center'
+  }}>
+  <Typography level="title-lg">맛있는 아침식사</Typography>
+  <Button size="sm" variant="plain" sx={{
+    p: 0.5
+  }}>
+  <MoreVertIcon />
+</Button>
+</div>
+<Typography level="body-sm" sx={{
+  color: 'text.secondary',
+  mb: 1
+}}>
+<LocationOnIcon sx={{
+  fontSize: 16
+}} /> 서울, 한국
+</Typography>
+<Typography level="body-md">건강하고 맛있는 아침 식사로 하루를 시작해보세요.</Typography>
+</CardContent>
+<CardActions>
+  <Button size="sm" variant="plain" startDecorator={<FavoriteIcon />}>
+    좋아요
+  </Button>
+  <Button size="sm" variant="plain" startDecorator={<ShareIcon />}>
+    공유
+  </Button>
+</CardActions>
+</Card>
+</div>
+```
+
+### Complex Layout
+
+복잡한 레이아웃을 가진 소셜 미디어 스타일 카드입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Card sx={{
+  maxWidth: 400
+}}>
+<CardContent sx={{
+  pb: 2
+}}>
+<div style={{
+  display: 'flex',
+  alignItems: 'center',
+  gap: '1rem',
+  marginBottom: '1rem'
+}}>
+<Avatar size="sm" src="https://i.pravatar.cc/40?img=1" />
+<div>
+  <Typography level="title-sm">김철수</Typography>
+  <Typography level="body-xs" sx={{
+    color: 'text.secondary'
+  }}>
+  5분 전
+</Typography>
+</div>
+</div>
+<Typography level="body-md" sx={{
+  mb: 2
+}}>
+오늘 정말 좋은 하루였습니다! 새로운 프로젝트를 시작했는데 너무 흥미진진해요. 팀원들과의 협업도 잘 되고 있고,
+앞으로가 기대됩니다.
+</Typography>
+</CardContent>
+<CardOverflow>
+  <AspectRatio ratio="2">
+    <img src="https://images.unsplash.com/photo-1519389950473-47ba0277781c?auto=format&fit=crop&w=400" loading="lazy" alt="Team work" />
+  </AspectRatio>
+</CardOverflow>
+<CardContent sx={{
+  pt: 1
+}}>
+<div style={{
+  display: 'flex',
+  alignItems: 'center',
+  gap: '1rem'
+}}>
+<Button size="sm" variant="plain" startDecorator={<FavoriteIcon />}>
+  12
+</Button>
+<Button size="sm" variant="plain" startDecorator={<ShareIcon />}>
+  공유
+</Button>
+<Typography level="body-xs" sx={{
+  ml: 'auto',
+  color: 'text.secondary'
+}}>
+댓글 3개
+</Typography>
+</div>
+</CardContent>
+</Card>
+</div>
+```
+
+## Card Components
+
+Card는 여러 하위 컴포넌트로 구성됩니다:
+
+### Card
+
+메인 카드 컨테이너입니다.
+
+```tsx
+<Card variant="outlined" color="neutral" size="md">
+  {/* 카드 내용 */}
+</Card>
+```
+
+### CardContent
+
+카드의 주요 내용을 담는 영역입니다.
+
+```tsx
+<CardContent>
+  <Typography level="title-lg">제목</Typography>
+  <Typography level="body-md">내용</Typography>
+</CardContent>
+```
+
+### CardCover
+
+카드 전체를 덮는 배경 이미지나 미디어를 표시합니다.
+
+```tsx
+<CardCover>
+  <img src="image.jpg" alt="Cover" />
+</CardCover>
+```
+
+### CardActions
+
+액션 버튼들을 배치하는 영역입니다.
+
+```tsx
+<CardActions>
+  <Button>확인</Button>
+  <Button>취소</Button>
+</CardActions>
+```
+
+### CardOverflow
+
+카드의 패딩을 무시하고 전체 너비를 사용하는 영역입니다.
+
+```tsx
+<CardOverflow>
+  <AspectRatio ratio="3/4">
+    <img src="full-width-image.jpg" alt="Full width" />
+  </AspectRatio>
+</CardOverflow>
+```
+
+## Common Use Cases
+
+### Product Cards
+
+```tsx
+<Card sx={{ maxWidth: 320 }}>
+  <CardOverflow>
+    <AspectRatio ratio="1">
+      <img src="product.jpg" alt="Product" />
+    </AspectRatio>
+  </CardOverflow>
+  <CardContent>
+    <Typography level="title-lg">제품명</Typography>
+    <Typography level="body-md">제품 설명</Typography>
+    <Typography level="title-lg" color="primary">
+      ₩199,000
+    </Typography>
+  </CardContent>
+  <CardActions>
+    <Button variant="solid" fullWidth>
+      구매하기
+    </Button>
+  </CardActions>
+</Card>
+```
+
+### User Profile Cards
+
+```tsx
+<Card sx={{ maxWidth: 320 }}>
+  <CardContent sx={{ alignItems: 'center', textAlign: 'center' }}>
+    <Avatar size="lg" src="profile.jpg" />
+    <Typography level="title-lg">사용자 이름</Typography>
+    <Typography level="body-sm">직책</Typography>
+  </CardContent>
+  <CardActions>
+    <Button size="sm" variant="soft">
+      팔로우
+    </Button>
+    <Button size="sm" variant="solid">
+      메시지
+    </Button>
+  </CardActions>
+</Card>
+```
+
+### News Cards
+
+```tsx
+<Card sx={{ maxWidth: 400 }}>
+  <CardOverflow>
+    <AspectRatio ratio="3/2">
+      <img src="news.jpg" alt="News" />
+    </AspectRatio>
+  </CardOverflow>
+  <CardContent>
+    <Typography level="body-xs" color="neutral">
+      뉴스 · 2시간 전
+    </Typography>
+    <Typography level="title-md">뉴스 제목</Typography>
+    <Typography level="body-sm">뉴스 요약...</Typography>
+  </CardContent>
+</Card>
+```
+
+### Dashboard Widget Cards
+
+```tsx
+<Card variant="soft" color="primary">
+  <CardContent>
+    <Typography level="body-sm">총 사용자</Typography>
+    <Typography level="h2">1,234</Typography>
+    <Typography level="body-xs">+12% from last month</Typography>
+  </CardContent>
+</Card>
+```
+
+## Best Practices
+
+1. **적절한 크기**: 카드의 내용에 맞는 적절한 크기를 설정하세요. 너무 크거나 작으면 가독성이 떨어집니다.
+
+2. **일관된 스타일**: 같은 맥락에서 사용되는 카드들은 일관된 variant, color, size를 사용하세요.
+
+3. **명확한 계층구조**: Typography의 level을 활용하여 정보의 중요도에 따른 시각적 계층을 만드세요.
+
+4. **적절한 간격**: 여러 카드를 나열할 때는 적절한 간격을 두어 각각을 구분할 수 있게 하세요.
+
+5. **접근성 고려**:
+   - 카드가 클릭 가능한 경우 키보드 탐색을 지원하세요
+   - 이미지에는 적절한 alt 텍스트를 제공하세요
+   - 색상만으로 정보를 전달하지 마세요
+
+6. **반응형 디자인**: 다양한 화면 크기에서 잘 작동하도록 maxWidth나 responsive 속성을 활용하세요.
+
+7. **로딩 상태**: 데이터를 불러오는 동안에는 Skeleton 컴포넌트를 활용하여 로딩 상태를 표시하세요.
+
+8. **액션 버튼**: CardActions에는 카드와 직접 관련된 주요 액션만 포함하세요. 너무 많은 버튼은 혼란을 야기할 수 있습니다.