@ceed/ads 1.13.4 → 1.15.0-next.2

package/dist/components/data-display/Badge.md

@@ -0,0 +1,315 @@
+# Badge
+
+## Introduction
+
+Badge 컴포넌트는 다른 UI 요소 위에 작은 카운트, 상태, 또는 레이블을 표시하는 데 사용됩니다. 주로 알림 수, 상태 표시기, 또는 새로운 콘텐츠를 나타내는 데 활용됩니다.
+
+```tsx
+<Badge {...args}>
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+```
+
+| Field        | Description         | Default   |
+| ------------ | ------------------- | --------- |
+| badgeContent | 배지에 표시될 내용          | 4         |
+| color        | 배지 색상               | "primary" |
+| variant      | 배지 스타일 변형           | "solid"   |
+| size         | 배지 크기               | "md"      |
+| invisible    | 배지 숨김 여부            | —         |
+| showZero     | 0일 때 표시 여부          | —         |
+| max          | 최대 표시 숫자 (99 → 99+) | —         |
+
+## Usage
+
+```tsx
+import { Badge, IconButton } from '@ceed/ads';
+import { NotificationsIcon } from '@mui/icons-material';
+
+function MyComponent() {
+  return (
+    <Badge badgeContent={4} color="danger">
+      <IconButton>
+        <NotificationsIcon />
+      </IconButton>
+    </Badge>
+  );
+}
+```
+
+## Examples
+
+### Basic Usage
+
+기본적인 Badge 사용법입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem'
+}}>
+<Badge badgeContent={4}>
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+
+<Badge badgeContent={100} max={99}>
+  <IconButton>
+    <EmailIcon />
+  </IconButton>
+</Badge>
+
+<Badge badgeContent="NEW">
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+</div>
+```
+
+### Colors
+
+다양한 색상을 적용할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem'
+}}>
+<Badge badgeContent={4} color="primary">
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+
+<Badge badgeContent={4} color="neutral">
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+
+<Badge badgeContent={4} color="danger">
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+
+<Badge badgeContent={4} color="success">
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+
+<Badge badgeContent={4} color="warning">
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+</div>
+```
+
+### Variants
+
+다양한 스타일 변형을 제공합니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem'
+}}>
+<Badge badgeContent={4} variant="solid">
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+
+<Badge badgeContent={4} variant="soft">
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+
+<Badge badgeContent={4} variant="outlined">
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+
+<Badge badgeContent={4} variant="plain">
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+</div>
+```
+
+### Sizes
+
+크기를 조절할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem',
+  alignItems: 'center'
+}}>
+<Badge badgeContent={4} size="sm">
+  <IconButton size="sm">
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+
+<Badge badgeContent={4} size="md">
+  <IconButton size="md">
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+
+<Badge badgeContent={4} size="lg">
+  <IconButton size="lg">
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+</div>
+```
+
+### With Avatar
+
+아바타와 함께 사용할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem'
+}}>
+<Badge badgeContent={4} color="danger">
+  <Avatar src="https://i.pravatar.cc/40?img=1" />
+</Badge>
+
+<Badge badgeContent="●" color="success">
+  <Avatar src="https://i.pravatar.cc/40?img=2" />
+</Badge>
+</div>
+```
+
+### Dot Badge
+
+내용 없이 점으로만 표시할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem'
+}}>
+<Badge variant="solid" color="danger">
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+
+<Badge variant="solid" color="success">
+  <Avatar src="https://i.pravatar.cc/40?img=3" />
+</Badge>
+</div>
+```
+
+### Max Count
+
+최대 카운트를 설정하여 숫자가 넘을 때 '+' 표시를 할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem'
+}}>
+<Badge badgeContent={99}>
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+
+<Badge badgeContent={100} max={99}>
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+
+<Badge badgeContent={1000} max={999}>
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+</div>
+```
+
+### Show Zero
+
+기본적으로 0일 때는 숨겨지지만, showZero 옵션으로 표시할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem'
+}}>
+<div>
+  <p>Default (0 숨김)</p>
+  <Badge badgeContent={0}>
+    <IconButton>
+      <NotificationsIcon />
+    </IconButton>
+  </Badge>
+</div>
+
+<div>
+  <p>Show zero</p>
+  <Badge badgeContent={0} showZero>
+    <IconButton>
+      <NotificationsIcon />
+    </IconButton>
+  </Badge>
+</div>
+</div>
+```
+
+## Common Use Cases
+
+### Notification Count
+
+```tsx
+<Badge badgeContent={unreadCount} color="danger">
+  <IconButton>
+    <NotificationsIcon />
+  </IconButton>
+</Badge>
+```
+
+### Status Indicator
+
+```tsx
+<Badge color="success" variant="solid">
+  <Avatar src="/user-avatar.jpg" />
+</Badge>
+```
+
+### New Items
+
+```tsx
+<Badge badgeContent="NEW" color="warning">
+  <Button>메뉴</Button>
+</Badge>
+```
+
+## Best Practices
+
+1. **의미 있는 색상**: 색상은 의미를 가지도록 사용하세요 (빨간색은 중요한 알림, 초록색은 성공 상태 등).
+
+2. **적절한 콘텐츠**: 너무 긴 텍스트는 피하고, 숫자나 짧은 텍스트를 사용하세요.
+
+3. **대비**: Badge의 색상이 배경과 충분한 대비를 가지도록 하세요.
+
+4. **접근성**: 시각적 정보만으로 의존하지 않고, 스크린 리더를 위한 적절한 레이블을 제공하세요.
+
+5. **일관성**: 애플리케이션 전체에서 Badge 사용 패턴을 일관되게 유지하세요.

package/dist/components/data-display/Chip.md

@@ -0,0 +1,301 @@
+# Chip
+
+## Introduction
+
+Chip 컴포넌트는 입력, 속성, 액션을 컴팩트하게 표현하는 UI 요소입니다. 태그, 필터, 연락처, 카테고리 등을 나타내는 데 주로 사용됩니다. 텍스트, 아이콘, 아바타와 함께 사용할 수 있으며, 클릭하거나 삭제할 수 있는 인터랙티브한 기능을 제공합니다.
+
+```tsx
+<Chip {...args} />
+```
+
+| Field    | Description | Default   |
+| -------- | ----------- | --------- |
+| children | Chip 내용     | "Chip"    |
+| color    | Chip 색상     | "primary" |
+| variant  | Chip 스타일 변형 | "solid"   |
+| size     | Chip 크기     | "md"      |
+| disabled | 비활성화 상태     | —         |
+
+## Usage
+
+```tsx
+import { Chip } from '@ceed/ads';
+
+function MyComponent() {
+  return (
+    <div>
+      <Chip>Basic Chip</Chip>
+      <Chip clickable onClick={() => console.log('clicked')}>
+        Clickable Chip
+      </Chip>
+      <Chip
+        endDecorator={<CloseIcon />}
+        onClick={() => console.log('delete')}
+      >
+        Deletable Chip
+      </Chip>
+    </div>
+  );
+}
+```
+
+## Examples
+
+### Basic Usage
+
+기본적인 Chip 사용법입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Chip>Basic Chip</Chip>
+<Chip disabled>Disabled</Chip>
+<Chip onClick={() => alert('Clicked!')}>Clickable</Chip>
+</div>
+```
+
+### Colors
+
+다양한 색상을 적용할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Chip color="primary">Primary</Chip>
+<Chip color="neutral">Neutral</Chip>
+<Chip color="danger">Danger</Chip>
+<Chip color="success">Success</Chip>
+<Chip color="warning">Warning</Chip>
+</div>
+```
+
+### Variants
+
+다양한 스타일 변형을 제공합니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Chip variant="solid">Solid</Chip>
+<Chip variant="soft">Soft</Chip>
+<Chip variant="outlined">Outlined</Chip>
+<Chip variant="plain">Plain</Chip>
+</div>
+```
+
+### Sizes
+
+크기를 조절할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  alignItems: 'center',
+  flexWrap: 'wrap'
+}}>
+<Chip size="sm">Small</Chip>
+<Chip size="md">Medium</Chip>
+<Chip size="lg">Large</Chip>
+</div>
+```
+
+### With Icons
+
+아이콘과 함께 사용할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Chip startDecorator={<Add />}>Add Item</Chip>
+<Chip endDecorator={<Close />}>Remove</Chip>
+<Chip startDecorator={<Done />} color="success">
+  Completed
+</Chip>
+</div>
+```
+
+### With Avatar
+
+아바타와 함께 사용하여 사용자를 나타낼 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Chip startDecorator={<Avatar size="sm" src="https://i.pravatar.cc/40?img=1" />}>John Doe</Chip>
+<Chip startDecorator={<Avatar size="sm" src="https://i.pravatar.cc/40?img=2" />}>Jane Smith</Chip>
+</div>
+```
+
+### Deletable
+
+삭제 기능을 가진 Chip입니다. 클릭하면 목록에서 제거됩니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+{chips.map(chip => <Chip key={chip} endDecorator={<Close />} onClick={() => handleDelete(chip)} variant="outlined">
+{chip}
+</Chip>)}
+</div>
+```
+
+### Clickable
+
+클릭 가능한 Chip으로 필터나 탭으로 사용할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Chip onClick={() => alert('Filter: All')}>All</Chip>
+<Chip onClick={() => alert('Filter: Active')} color="success">
+  Active
+</Chip>
+<Chip onClick={() => alert('Filter: Completed')} color="neutral">
+  Completed
+</Chip>
+</div>
+```
+
+### Clickable Actions
+
+클릭하여 다양한 액션을 수행할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<Chip onClick={() => window.open('#', '_blank')}>Home</Chip>
+<Chip onClick={() => window.open('#', '_blank')} variant="outlined">
+  About
+</Chip>
+<Chip onClick={() => window.open('#', '_blank')} variant="soft">
+  Contact
+</Chip>
+</div>
+```
+
+### States
+
+다양한 상태를 표현할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  flexWrap: 'wrap'
+}}>
+<div>
+  <h4>Normal</h4>
+  <div style={{
+    display: 'flex',
+    gap: '0.5rem',
+    flexWrap: 'wrap'
+  }}>
+  <Chip>Default</Chip>
+  <Chip onClick={() => {}}>Clickable</Chip>
+  <Chip endDecorator={<Close />}>Deletable</Chip>
+</div>
+</div>
+<div>
+  <h4>Disabled</h4>
+  <div style={{
+    display: 'flex',
+    gap: '0.5rem',
+    flexWrap: 'wrap'
+  }}>
+  <Chip disabled>Default</Chip>
+  <Chip disabled onClick={() => {}}>
+    Clickable
+  </Chip>
+  <Chip disabled endDecorator={<Close />}>
+    Deletable
+  </Chip>
+</div>
+</div>
+</div>
+```
+
+## Common Use Cases
+
+### Tags
+
+```tsx
+<div style={{ display: 'flex', gap: '0.5rem' }}>
+  <Chip variant="outlined">React</Chip>
+  <Chip variant="outlined">TypeScript</Chip>
+  <Chip variant="outlined">JavaScript</Chip>
+</div>
+```
+
+### Status Indicators
+
+```tsx
+<Chip color="success" startDecorator={<CheckIcon />}>
+  Completed
+</Chip>
+<Chip color="warning" startDecorator={<ClockIcon />}>
+  In Progress
+</Chip>
+```
+
+### Filter Controls
+
+```tsx
+<Chip
+  clickable
+  variant={isActive ? 'solid' : 'outlined'}
+  onClick={() => setFilter('all')}
+>
+  All Items
+</Chip>
+```
+
+### Contact Pills
+
+```tsx
+<Chip
+  startDecorator={<Avatar size="sm" />}
+  endDecorator={<CloseIcon />}
+  onDelete={() => removeContact(id)}
+>
+  John Doe
+</Chip>
+```
+
+## Best Practices
+
+1. **적절한 크기**: 콘텐츠에 맞는 적절한 크기를 선택하세요. 긴 텍스트는 피하고 간결하게 표현하세요.
+
+2. **일관된 스타일**: 같은 맥락에서는 일관된 variant와 color를 사용하세요.
+
+3. **명확한 액션**: clickable이나 deletable 기능을 사용할 때는 사용자에게 명확한 피드백을 제공하세요.
+
+4. **접근성**: 키보드 탐색이 가능하도록 하고, 스크린 리더를 위한 적절한 레이블을 제공하세요.
+
+5. **적절한 간격**: 여러 Chip을 나열할 때는 적절한 간격을 두어 가독성을 높이세요.
+
+6. **색상 의미**: 색상은 의미를 가지도록 사용하세요 (성공은 초록색, 경고는 주황색 등).