@ceed/cds 1.28.1 → 1.29.0-next.1

package/dist/components/surfaces/Divider.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-Divider is a visual separator component that draws a thin line between content sections. It helps organize layouts by creating clear visual boundaries between groups of related content. Built on Joy UI's Divider component, it supports horizontal and vertical orientations, multiple color options, and Framer Motion animation props for animated transitions.
-
-Dividers are commonly used to separate list items, form sections, card content areas, navigation groups, and dashboard panels. They can optionally contain centered text to label the sections they divide.
+Divider 컴포넌트는 콘텐츠를 시각적으로 구분하는 선을 그려주는 컴포넌트입니다. Joy UI의 Divider 컴포넌트를 기반으로 하며, Framer Motion 애니메이션 지원이 추가되었습니다. 리스트 항목, 카드 섹션, 폼 영역 등을 구분할 때 사용하여 콘텐츠의 가독성을 향상시킬 수 있습니다.
 
 ```tsx
 <Box sx={{
@@ -34,17 +32,19 @@ import { Divider } from '@ceed/cds';
 function MyComponent() {
   return (
     <div>
-      <p>First section</p>
+      <p>첫 번째 콘텐츠</p>
       <Divider />
-      <p>Second section</p>
+      <p>두 번째 콘텐츠</p>
     </div>
   );
 }
 ```
 
-## Basic
+## Examples
+
+### Basic Usage
 
-The simplest usage of Divider in both horizontal and vertical orientations.
+가장 기본적인 Divider 사용법입니다.
 
 ```tsx
 <Stack spacing={3}>
@@ -81,9 +81,9 @@ The simplest usage of Divider in both horizontal and vertical orientations.
 </Stack>
 ```
 
-## Orientations
+### Orientations
 
-Divider supports `horizontal` (default) and `vertical` orientations. Vertical dividers are useful for separating inline or row-based content.
+구분선의 방향을 설정할 수 있습니다.
 
 ```tsx
 <Stack spacing={4}>
@@ -118,9 +118,9 @@ Vertical
 </Stack>
 ```
 
-## Colors
+### Colors
 
-Apply semantic colors to dividers for emphasis or to match the surrounding context.
+다양한 색상을 적용할 수 있습니다.
 
 ```tsx
 <Stack spacing={3}>
@@ -140,9 +140,9 @@ Apply semantic colors to dividers for emphasis or to match the surrounding conte
 </Stack>
 ```
 
-## With Text
+### With Text
 
-Place text or other elements inside a Divider to create labeled section breaks (e.g., "OR" between login options).
+구분선 중앙에 텍스트를 배치할 수 있습니다.
 
 ```tsx
 <Stack spacing={3}>
@@ -172,9 +172,9 @@ Place text or other elements inside a Divider to create labeled section breaks (
 </Stack>
 ```
 
-## In Cards
+### In Cards
 
-Use Dividers within cards and panels to separate distinct content sections.
+카드나 패널 내에서 섹션을 구분하는 용도로 사용할 수 있습니다.
 
 ```tsx
 <Stack direction="row" spacing={3}>
@@ -272,9 +272,9 @@ Use Dividers within cards and panels to separate distinct content sections.
 </Stack>
 ```
 
-## List Separators
+### List Separators
 
-Dividers work naturally as separators between list items.
+목록 항목들을 구분하는 구분선으로 사용할 수 있습니다.
 
 ```tsx
 <Sheet variant="outlined" sx={{
@@ -316,9 +316,9 @@ Dividers work naturally as separators between list items.
 </Sheet>
 ```
 
-## Responsive Orientation
+### Responsive Orientation
 
-Divider orientation can change based on screen size using responsive values, switching from horizontal on mobile to vertical on larger screens.
+화면 크기에 따라 방향을 변경할 수 있습니다.
 
 ```tsx
 <Stack spacing={3}>
@@ -369,9 +369,9 @@ Divider orientation can change based on screen size using responsive values, swi
 </Stack>
 ```
 
-## With Motion
+### With Motion
 
-Framer Motion animation props can be applied directly to Divider for animated reveal effects.
+Framer Motion 애니메이션을 적용할 수 있습니다.
 
 ```tsx
 <Stack spacing={3}>
@@ -438,9 +438,9 @@ Framer Motion animation props can be applied directly to Divider for animated re
 </Stack>
 ```
 
-## Custom Styling
+### Custom Styling
 
-Advanced styling techniques including rounded corners, gradients (using Box), and shadow effects.
+CSS 스타일을 이용해 구분선을 커스터마이징할 수 있습니다.
 
 ```tsx
 <Stack spacing={4}>
@@ -515,97 +515,248 @@ borderRadius: '1px'
 </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
 
-### Form Section Break
+### Navigation Sections
 
 ```tsx
-import { Divider, Stack, FormControl, FormLabel, Input, Typography } from '@ceed/cds';
+<nav>
+  <Link href="/home">Home</Link>
+  <Link href="/about">About</Link>
 
-function SectionedForm() {
-  return (
-    <Stack spacing={2}>
-      <Typography level="title-md">Personal Info</Typography>
-      <FormControl>
-        <FormLabel>Name</FormLabel>
-        <Input />
-      </FormControl>
-      <FormControl>
-        <FormLabel>Email</FormLabel>
-        <Input type="email" />
-      </FormControl>
+  <Divider sx={{ my: 1 }} />
 
-      <Divider sx={{ my: 3 }}>Additional Info</Divider>
+  <Link href="/login">Login</Link>
+  <Link href="/signup">Sign Up</Link>
+</nav>
+```
 
-      <FormControl>
-        <FormLabel>Company</FormLabel>
-        <Input />
-      </FormControl>
+### 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>
 ```
 
-### Login Separator
+### List Items
 
 ```tsx
-import { Divider, Stack, Button, Typography } from '@ceed/cds';
+<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>
+```
 
-function LoginOptions() {
-  return (
-    <Stack spacing={2} sx={{ maxWidth: 400 }}>
-      <Button fullWidth>Sign in with Email</Button>
+### Dashboard Sections
 
-      <Divider>or</Divider>
+```tsx
+<Sheet variant="outlined" sx={{ p: 3 }}>
+  <Typography level="title-lg">대시보드</Typography>
 
-      <Button fullWidth variant="outlined">Sign in with Google</Button>
-      <Button fullWidth variant="outlined">Sign in with GitHub</Button>
-    </Stack>
-  );
-}
+  <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>
 ```
 
-### Dashboard Section Separator
+### Modal Content
 
 ```tsx
-import { Divider, Sheet, Typography, Stack } from '@ceed/cds';
+<Modal open={open}>
+  <Sheet variant="outlined" sx={{ p: 4, borderRadius: 'md' }}>
+    <Typography level="title-lg">설정</Typography>
 
-function Dashboard() {
-  return (
-    <Sheet variant="outlined" sx={{ p: 3 }}>
-      <Typography level="title-lg">Dashboard</Typography>
+    <Divider sx={{ my: 2 }} />
 
-      <Divider sx={{ my: 2 }} />
+    <Stack spacing={2}>
+      <FormControl>
+        <FormLabel>알림 설정</FormLabel>
+        <Switch />
+      </FormControl>
 
-      <Typography level="title-md">Recent Activity</Typography>
-      {/* Activity list */}
+      <FormControl>
+        <FormLabel>테마 설정</FormLabel>
+        <Select defaultValue="light">
+          <Option value="light">Light</Option>
+          <Option value="dark">Dark</Option>
+        </Select>
+      </FormControl>
+    </Stack>
 
-      <Divider sx={{ my: 2 }} />
+    <Divider sx={{ my: 3 }} />
 
-      <Typography level="title-md">Statistics</Typography>
-      {/* Stats content */}
-    </Sheet>
-  );
-}
+    <Stack direction="row" spacing={2} justifyContent="flex-end">
+      <Button variant="outlined" onClick={handleClose}>
+        취소
+      </Button>
+      <Button onClick={handleSave}>저장</Button>
+    </Stack>
+  </Sheet>
+</Modal>
 ```
 
 ## Best Practices
 
-- **Use adequate margin around dividers.** Apply `my` (vertical margin) for horizontal dividers and `mx` (horizontal margin) for vertical dividers to give surrounding content breathing room.
+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 }}
+/>
+```
 
-- **Do not overuse dividers.** If content sections are already visually distinct through background colors, spacing, or card boundaries, adding a divider is redundant.
-  - ✔ Use a Divider between items in a flat list
-  - ✘ Add a Divider between cards that already have borders
+## When to Use Divider
 
-- **Set explicit height for vertical dividers.** Vertical dividers require a parent with a defined height, or an explicit `height` value via `sx`, to render correctly.
+### ✅ 사용하기 좋은 경우
 
-- **Use responsive orientation for adaptive layouts.** When a row layout collapses to a column on mobile, switch the divider orientation accordingly using responsive values.
+- **리스트 항목 구분**: 긴 리스트에서 항목들을 명확히 구분할 때
+- **폼 섹션 구분**: 관련 필드들을 그룹으로 나눌 때
+- **카드 내 콘텐츠 구분**: 카드 내에서 다른 성격의 정보를 구분할 때
+- **네비게이션 메뉴**: 메뉴 그룹을 시각적으로 구분할 때
+- **대시보드 섹션**: 대시보드의 위젯이나 섹션을 구분할 때
 
-- **Reserve text-bearing dividers for clear context switches.** Only use dividers with text (e.g., "OR", "Section 2") when the label genuinely helps users understand the content transition.
+### ❌ 사용하지 않는 것이 좋은 경우
 
-## Accessibility
+- **단순한 여백으로 충분한 경우**: 과도한 구분선 사용은 피하세요
+- **이미 다른 구분 요소가 있는 경우**: 색상, 배경, 테두리 등으로 이미 구분되어 있다면 불필요
+- **너무 짧은 콘텐츠**: 한두 줄 정도의 짧은 콘텐츠에는 구분선이 과할 수 있습니다
 
-- Divider renders with `role="separator"` by default, which screen readers recognize as a visual boundary. No additional ARIA attributes are needed for purely decorative dividers.
-- When a Divider contains text (e.g., `<Divider>or</Divider>`), the text is readable by screen readers and provides semantic context for the content transition.
-- Dividers are non-interactive and non-focusable, so they do not interfere with keyboard navigation.
-- If you need a semantic section break rather than a visual one, use appropriate HTML elements (`<section>`, `<hr>`) alongside or instead of Divider.
+Divider는 콘텐츠의 구조를 명확히 하고 가독성을 향상시키는 유용한 도구입니다. 적절히 사용하면 사용자가 정보를 더 쉽게 이해할 수 있는 인터페이스를 만들 수 있습니다.