@ceed/ads 1.13.4 → 1.15.0-next.2

package/dist/components/surfaces/Divider.md

@@ -0,0 +1,762 @@
+# Divider
+
+## Introduction
+
+Divider 컴포넌트는 콘텐츠를 시각적으로 구분하는 선을 그려주는 컴포넌트입니다. Joy UI의 Divider 컴포넌트를 기반으로 하며, Framer Motion 애니메이션 지원이 추가되었습니다. 리스트 항목, 카드 섹션, 폼 영역 등을 구분할 때 사용하여 콘텐츠의 가독성을 향상시킬 수 있습니다.
+
+```tsx
+<Box sx={{
+  width: 300,
+  height: 200,
+  p: 3
+}}>
+<Typography level="body-md">위 콘텐츠</Typography>
+<Divider {...args} sx={{
+  my: 2
+}} />
+<Typography level="body-md">아래 콘텐츠</Typography>
+</Box>
+```
+
+| Field       | Description | Default      |
+| ----------- | ----------- | ------------ |
+| orientation | 구분선의 방향     | "horizontal" |
+| inset       | 구분선의 들여쓰기   | —            |
+| color       | 구분선의 색상     | —            |
+
+## Usage
+
+```tsx
+import { Divider } from '@ceed/ads';
+
+function MyComponent() {
+  return (
+    <div>
+      <p>첫 번째 콘텐츠</p>
+      <Divider />
+      <p>두 번째 콘텐츠</p>
+    </div>
+  );
+}
+```
+
+## Examples
+
+### Basic Usage
+
+가장 기본적인 Divider 사용법입니다.
+
+```tsx
+<Stack spacing={3}>
+  <Box>
+    <Typography level="title-md" sx={{
+      mb: 2
+    }}>
+    기본 수평 구분선
+  </Typography>
+  <Typography level="body-sm">첫 번째 콘텐츠</Typography>
+  <Divider sx={{
+    my: 1
+  }} />
+  <Typography level="body-sm">두 번째 콘텐츠</Typography>
+</Box>
+
+<Box sx={{
+  display: 'flex',
+  alignItems: 'center',
+  height: 60
+}}>
+<Typography level="title-md" sx={{
+  mr: 2
+}}>
+수직 구분선
+</Typography>
+<Divider orientation="vertical" />
+<Typography level="title-md" sx={{
+  ml: 2
+}}>
+다른 섹션
+</Typography>
+</Box>
+</Stack>
+```
+
+### Orientations
+
+구분선의 방향을 설정할 수 있습니다.
+
+```tsx
+<Stack spacing={4}>
+  <Box>
+    <Typography level="title-sm" sx={{
+      mb: 2
+    }}>
+    Horizontal (기본)
+  </Typography>
+  <Typography level="body-sm">첫 번째 섹션</Typography>
+  <Divider orientation="horizontal" sx={{
+    my: 1
+  }} />
+  <Typography level="body-sm">두 번째 섹션</Typography>
+</Box>
+
+<Box sx={{
+  display: 'flex',
+  alignItems: 'center',
+  height: 80
+}}>
+<Typography level="title-sm" sx={{
+  mr: 2
+}}>
+Vertical
+</Typography>
+<Divider orientation="vertical" sx={{
+  mx: 2
+}} />
+<Typography level="title-sm">수직 구분선은 요소들을 좌우로 구분합니다</Typography>
+</Box>
+</Stack>
+```
+
+### Colors
+
+다양한 색상을 적용할 수 있습니다.
+
+```tsx
+<Stack spacing={3}>
+  {['primary', 'neutral', 'danger', 'success', 'warning'].map(color => <Box key={color}>
+  <Typography level="title-sm" sx={{
+    mb: 1,
+    textTransform: 'capitalize'
+  }}>
+  {color}
+</Typography>
+<Typography level="body-sm">위 콘텐츠</Typography>
+<Divider color={color as any} sx={{
+  my: 1
+}} />
+<Typography level="body-sm">아래 콘텐츠</Typography>
+</Box>)}
+</Stack>
+```
+
+### With Text
+
+구분선 중앙에 텍스트를 배치할 수 있습니다.
+
+```tsx
+<Stack spacing={3}>
+  <Box>
+    <Typography level="body-md">로그인 정보</Typography>
+    <Divider sx={{
+      my: 2
+    }}>또는</Divider>
+    <Typography level="body-md">소셜 로그인</Typography>
+  </Box>
+
+  <Box>
+    <Typography level="body-md">개인 정보</Typography>
+    <Divider sx={{
+      my: 2,
+      '&::before, &::after': {
+        border: '1px solid',
+        borderColor: 'primary.500'
+      }
+    }}>
+    <Typography level="title-sm" color="primary">
+      추가 정보
+    </Typography>
+  </Divider>
+  <Typography level="body-md">추가 세부사항</Typography>
+</Box>
+</Stack>
+```
+
+### In Cards
+
+카드나 패널 내에서 섹션을 구분하는 용도로 사용할 수 있습니다.
+
+```tsx
+<Stack direction="row" spacing={3}>
+  <Sheet variant="outlined" sx={{
+    p: 3,
+    minWidth: 250,
+    borderRadius: 'md'
+  }}>
+  <Typography level="title-lg" sx={{
+    mb: 2
+  }}>
+  사용자 정보
+</Typography>
+<Typography level="body-sm" sx={{
+  mb: 1
+}}>
+이름: 김철수
+</Typography>
+<Typography level="body-sm" sx={{
+  mb: 2
+}}>
+이메일: kim@example.com
+</Typography>
+
+<Divider sx={{
+  my: 2
+}} />
+
+<Typography level="title-md" sx={{
+  mb: 2
+}}>
+통계
+</Typography>
+<Typography level="body-sm" sx={{
+  mb: 1
+}}>
+가입일: 2024.01.15
+</Typography>
+<Typography level="body-sm">활동 점수: 1,234</Typography>
+</Sheet>
+
+<Sheet variant="outlined" sx={{
+  p: 3,
+  minWidth: 250,
+  borderRadius: 'md'
+}}>
+<Typography level="title-lg" sx={{
+  mb: 2
+}}>
+프로젝트 현황
+</Typography>
+
+<Box sx={{
+  display: 'flex',
+  justifyContent: 'space-between',
+  mb: 1
+}}>
+<Typography level="body-sm">완료</Typography>
+<Typography level="body-sm" color="success">
+  12
+</Typography>
+</Box>
+
+<Divider color="neutral" sx={{
+  my: 1,
+  opacity: 0.3
+}} />
+
+<Box sx={{
+  display: 'flex',
+  justifyContent: 'space-between',
+  mb: 1
+}}>
+<Typography level="body-sm">진행중</Typography>
+<Typography level="body-sm" color="warning">
+  5
+</Typography>
+</Box>
+
+<Divider color="neutral" sx={{
+  my: 1,
+  opacity: 0.3
+}} />
+
+<Box sx={{
+  display: 'flex',
+  justifyContent: 'space-between'
+}}>
+<Typography level="body-sm">대기</Typography>
+<Typography level="body-sm" color="neutral">
+  3
+</Typography>
+</Box>
+</Sheet>
+</Stack>
+```
+
+### List Separators
+
+목록 항목들을 구분하는 구분선으로 사용할 수 있습니다.
+
+```tsx
+<Sheet variant="outlined" sx={{
+  maxWidth: 400,
+  borderRadius: 'md'
+}}>
+<Stack>
+  <Box sx={{
+    p: 2
+  }}>
+  <Typography level="body-md">첫 번째 항목</Typography>
+  <Typography level="body-xs" color="neutral">
+    첫 번째 항목에 대한 설명입니다.
+  </Typography>
+</Box>
+
+<Divider />
+
+<Box sx={{
+  p: 2
+}}>
+<Typography level="body-md">두 번째 항목</Typography>
+<Typography level="body-xs" color="neutral">
+  두 번째 항목에 대한 설명입니다.
+</Typography>
+</Box>
+
+<Divider />
+
+<Box sx={{
+  p: 2
+}}>
+<Typography level="body-md">세 번째 항목</Typography>
+<Typography level="body-xs" color="neutral">
+  세 번째 항목에 대한 설명입니다.
+</Typography>
+</Box>
+</Stack>
+</Sheet>
+```
+
+### Responsive Orientation
+
+화면 크기에 따라 방향을 변경할 수 있습니다.
+
+```tsx
+<Stack spacing={3}>
+  <Typography level="title-md">화면 크기에 따라 방향이 바뀌는 구분선</Typography>
+
+  <Box sx={{
+    display: 'flex',
+    flexDirection: {
+      xs: 'column',
+      sm: 'row'
+    },
+    alignItems: 'center',
+    gap: 2,
+    p: 3,
+    bgcolor: 'background.level1',
+    borderRadius: 'md'
+  }}>
+  <Typography level="body-md" sx={{
+    textAlign: 'center'
+  }}>
+  첫 번째 섹션
+</Typography>
+
+<Divider orientation={{
+  xs: 'horizontal',
+  sm: 'vertical'
+} as any} sx={{
+  width: {
+    xs: '100%',
+    sm: 'auto'
+  },
+  height: {
+    xs: 'auto',
+    sm: 40
+  }
+}} />
+
+<Typography level="body-md" sx={{
+  textAlign: 'center'
+}}>
+두 번째 섹션
+</Typography>
+</Box>
+
+<Typography level="body-xs" color="neutral">
+  * 화면 크기를 조절하여 구분선 방향 변화를 확인하세요
+</Typography>
+</Stack>
+```
+
+### With Motion
+
+Framer Motion 애니메이션을 적용할 수 있습니다.
+
+```tsx
+<Stack spacing={3}>
+  <Typography level="title-md">Framer Motion 애니메이션이 적용된 구분선</Typography>
+
+  <Box sx={{
+    p: 3,
+    bgcolor: 'background.level1',
+    borderRadius: 'md'
+  }}>
+  <Typography level="body-md" sx={{
+    mb: 2
+  }}>
+  위 콘텐츠
+</Typography>
+
+<Divider initial={{
+  scaleX: 0
+}} animate={{
+  scaleX: 1
+}} transition={{
+  duration: 1,
+  ease: 'easeOut'
+}} sx={{
+  my: 2,
+  transformOrigin: 'left'
+}} />
+
+<Typography level="body-md">아래 콘텐츠 (구분선이 애니메이션과 함께 나타남)</Typography>
+</Box>
+
+<Box sx={{
+  display: 'flex',
+  alignItems: 'center',
+  p: 3,
+  bgcolor: 'background.level1',
+  borderRadius: 'md'
+}}>
+<Typography level="body-md" sx={{
+  mr: 3
+}}>
+좌측 콘텐츠
+</Typography>
+
+<Divider orientation="vertical" initial={{
+  scaleY: 0
+}} animate={{
+  scaleY: 1
+}} transition={{
+  duration: 1,
+  delay: 0.5
+}} sx={{
+  mx: 2,
+  height: 40,
+  transformOrigin: 'top'
+}} />
+
+<Typography level="body-md" sx={{
+  ml: 3
+}}>
+우측 콘텐츠
+</Typography>
+</Box>
+</Stack>
+```
+
+### Custom Styling
+
+CSS 스타일을 이용해 구분선을 커스터마이징할 수 있습니다.
+
+```tsx
+<Stack spacing={4}>
+  <Box>
+    <Typography level="title-sm" sx={{
+      mb: 2
+    }}>
+    둥근 모서리 구분선
+  </Typography>
+  <Typography level="body-sm">위 콘텐츠</Typography>
+  <Divider sx={{
+    my: 2,
+    borderWidth: 3,
+    borderRadius: '6px',
+    borderColor: 'primary.500'
+  }} />
+  <Typography level="body-sm">아래 콘텐츠</Typography>
+</Box>
+
+<Box>
+  <Typography level="title-sm" sx={{
+    mb: 2
+  }}>
+  그라데이션 구분선 (Box 사용)
+</Typography>
+<Typography level="body-sm">위 콘텐츠</Typography>
+<Box sx={{
+  height: 2,
+  my: 2,
+  background: 'linear-gradient(90deg, transparent, #0073e6, transparent)',
+  borderRadius: '1px'
+}} />
+<Typography level="body-sm">아래 콘텐츠</Typography>
+</Box>
+
+<Box>
+  <Typography level="title-sm" sx={{
+    mb: 2
+  }}>
+  패턴 구분선 (Box 사용)
+</Typography>
+<Typography level="body-sm">위 콘텐츠</Typography>
+<Box sx={{
+  height: 3,
+  my: 2,
+  background: `repeating-linear-gradient(
+  90deg,
+  #0073e6 0px,
+  #0073e6 10px,
+  transparent 10px,
+  transparent 20px
+)`,
+borderRadius: '1px'
+}} />
+<Typography level="body-sm">아래 콘텐츠</Typography>
+</Box>
+
+<Box>
+  <Typography level="title-sm" sx={{
+    mb: 2
+  }}>
+  그림자 효과
+</Typography>
+<Typography level="body-sm">위 콘텐츠</Typography>
+<Divider sx={{
+  my: 2,
+  borderColor: 'neutral.500',
+  filter: 'drop-shadow(0px 1px 2px rgba(0, 0, 0, 0.2))'
+}} />
+<Typography level="body-sm">아래 콘텐츠</Typography>
+</Box>
+</Stack>
+```
+
+## Key Props
+
+### orientation
+
+구분선의 방향을 설정합니다.
+
+```tsx
+<Divider orientation="horizontal" /> {/* 기본값 */}
+<Divider orientation="vertical" />
+
+{/* 반응형 방향 */}
+<Divider orientation={{ xs: 'horizontal', sm: 'vertical' }} />
+```
+
+### variant
+
+구분선의 스타일을 설정합니다.
+
+```tsx
+<Divider variant="solid" />    {/* 기본값 - 실선 */}
+<Divider variant="plain" />    {/* 평면 스타일 */}
+<Divider variant="soft" />     {/* 부드러운 스타일 */}
+```
+
+### color
+
+구분선의 색상을 설정합니다.
+
+```tsx
+<Divider color="neutral" />    {/* 기본값 */}
+<Divider color="primary" />
+<Divider color="danger" />
+<Divider color="success" />
+<Divider color="warning" />
+```
+
+## Common Use Cases
+
+### Navigation Sections
+
+```tsx
+<nav>
+  <Link href="/home">Home</Link>
+  <Link href="/about">About</Link>
+
+  <Divider sx={{ my: 1 }} />
+
+  <Link href="/login">Login</Link>
+  <Link href="/signup">Sign Up</Link>
+</nav>
+```
+
+### Form Sections
+
+```tsx
+<form>
+  <Stack spacing={2}>
+    <Typography level="title-md">개인 정보</Typography>
+    <FormControl>
+      <FormLabel>이름</FormLabel>
+      <Input />
+    </FormControl>
+    <FormControl>
+      <FormLabel>이메일</FormLabel>
+      <Input type="email" />
+    </FormControl>
+
+    <Divider sx={{ my: 3 }}>추가 정보</Divider>
+
+    <FormControl>
+      <FormLabel>회사명</FormLabel>
+      <Input />
+    </FormControl>
+  </Stack>
+</form>
+```
+
+### Card Content Separation
+
+```tsx
+<Card>
+  <CardContent>
+    <Typography level="title-lg">제품명</Typography>
+    <Typography level="body-md">제품 설명...</Typography>
+
+    <Divider sx={{ my: 2 }} />
+
+    <Stack direction="row" justifyContent="space-between">
+      <Typography level="title-lg" color="primary">
+        ₩99,000
+      </Typography>
+      <Button>장바구니</Button>
+    </Stack>
+  </CardContent>
+</Card>
+```
+
+### List Items
+
+```tsx
+<Stack>
+  {items.map((item, index) => (
+    <React.Fragment key={item.id}>
+      <Box sx={{ p: 2 }}>
+        <Typography level="title-sm">{item.title}</Typography>
+        <Typography level="body-sm">{item.description}</Typography>
+      </Box>
+      {index < items.length - 1 && <Divider />}
+    </React.Fragment>
+  ))}
+</Stack>
+```
+
+### Dashboard Sections
+
+```tsx
+<Sheet variant="outlined" sx={{ p: 3 }}>
+  <Typography level="title-lg">대시보드</Typography>
+
+  <Divider sx={{ my: 2 }} />
+
+  <Grid container spacing={2}>
+    <Grid item xs={12} sm={6}>
+      <StatCard title="사용자" value="1,234" />
+    </Grid>
+    <Grid item xs={12} sm={6}>
+      <StatCard title="매출" value="₩5.6M" />
+    </Grid>
+  </Grid>
+
+  <Divider sx={{ my: 2 }} />
+
+  <Typography level="title-md">최근 활동</Typography>
+  {/* 활동 목록 */}
+</Sheet>
+```
+
+### Modal Content
+
+```tsx
+<Modal open={open}>
+  <Sheet variant="outlined" sx={{ p: 4, borderRadius: 'md' }}>
+    <Typography level="title-lg">설정</Typography>
+
+    <Divider sx={{ my: 2 }} />
+
+    <Stack spacing={2}>
+      <FormControl>
+        <FormLabel>알림 설정</FormLabel>
+        <Switch />
+      </FormControl>
+
+      <FormControl>
+        <FormLabel>테마 설정</FormLabel>
+        <Select defaultValue="light">
+          <Option value="light">Light</Option>
+          <Option value="dark">Dark</Option>
+        </Select>
+      </FormControl>
+    </Stack>
+
+    <Divider sx={{ my: 3 }} />
+
+    <Stack direction="row" spacing={2} justifyContent="flex-end">
+      <Button variant="outlined" onClick={handleClose}>
+        취소
+      </Button>
+      <Button onClick={handleSave}>저장</Button>
+    </Stack>
+  </Sheet>
+</Modal>
+```
+
+## Best Practices
+
+1. **적절한 여백**: 구분선 위아래에 충분한 여백을 두어 콘텐츠가 명확히 구분되도록 하세요.
+
+2. **의미있는 구분**: 논리적으로 관련 있는 콘텐츠끼리 그룹화하고 구분선으로 섹션을 나누세요.
+
+3. **과도한 사용 금지**: 너무 많은 구분선은 인터페이스를 복잡하게 만들 수 있습니다.
+
+4. **수직 구분선 사용**: 수직 구분선을 사용할 때는 부모 컨테이너의 높이를 명시해주세요.
+
+5. **반응형 고려**: 모바일에서는 수직 구분선이 수평으로 변경되어야 할 수 있습니다.
+
+6. **색상 일관성**: 프로젝트 전반에서 일관된 구분선 색상과 스타일을 사용하세요.
+
+7. **접근성**:
+   - 구분선은 단순히 시각적 구분을 위한 것이므로 스크린 리더에서는 무시됩니다
+   - 의미적 구분이 필요한 경우 적절한 HTML 섹션 태그를 함께 사용하세요
+
+## Responsive Behavior
+
+Divider는 모든 props에서 반응형 값을 지원합니다:
+
+```tsx
+<Divider
+  orientation={{ xs: 'horizontal', md: 'vertical' }}
+  sx={{
+    width: { xs: '100%', md: 'auto' },
+    height: { xs: 'auto', md: 50 },
+    my: { xs: 2, md: 0 },
+    mx: { xs: 0, md: 2 },
+  }}
+/>
+```
+
+## Motion Support
+
+Divider는 Framer Motion을 지원합니다:
+
+```tsx
+<Divider
+  initial={{ scaleX: 0 }}
+  animate={{ scaleX: 1 }}
+  transition={{ duration: 0.5 }}
+  sx={{ transformOrigin: 'left' }}
+/>
+
+<Divider
+  orientation="vertical"
+  initial={{ scaleY: 0 }}
+  animate={{ scaleY: 1 }}
+  whileHover={{ scaleY: 1.1 }}
+  transition={{ duration: 0.3 }}
+/>
+```
+
+## When to Use Divider
+
+### ✅ 사용하기 좋은 경우
+
+- **리스트 항목 구분**: 긴 리스트에서 항목들을 명확히 구분할 때
+- **폼 섹션 구분**: 관련 필드들을 그룹으로 나눌 때
+- **카드 내 콘텐츠 구분**: 카드 내에서 다른 성격의 정보를 구분할 때
+- **네비게이션 메뉴**: 메뉴 그룹을 시각적으로 구분할 때
+- **대시보드 섹션**: 대시보드의 위젯이나 섹션을 구분할 때
+
+### ❌ 사용하지 않는 것이 좋은 경우
+
+- **단순한 여백으로 충분한 경우**: 과도한 구분선 사용은 피하세요
+- **이미 다른 구분 요소가 있는 경우**: 색상, 배경, 테두리 등으로 이미 구분되어 있다면 불필요
+- **너무 짧은 콘텐츠**: 한두 줄 정도의 짧은 콘텐츠에는 구분선이 과할 수 있습니다
+
+Divider는 콘텐츠의 구조를 명확히 하고 가독성을 향상시키는 유용한 도구입니다. 적절히 사용하면 사용자가 정보를 더 쉽게 이해할 수 있는 인터페이스를 만들 수 있습니다.