@ceed/cds 1.29.0 → 1.30.0

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.
+The Divider component draws a line that visually separates content. It is based on Joy UI's Divider component and adds Framer Motion animation support. You can use it to separate list items, card sections, form areas, and more to improve content readability.
 
 ```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.
+The most basic way to use 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.
+You can set the direction of the divider.
 
 ```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.
+You can apply various colors.
 
 ```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).
+You can place text in the center of the divider.
 
 ```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.
+You can use it to separate sections inside cards or panels.
 
 ```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.
+You can use it as a separator 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.
+You can change the orientation based on screen size.
 
 ```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.
+You can apply Framer Motion animations.
 
 ```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.
+You can customize the divider with CSS styles.
 
 ```tsx
 <Stack spacing={4}>
@@ -515,97 +515,261 @@ borderRadius: '1px'
 </Stack>
 ```
 
+## Key Props
+
+### orientation
+
+Sets the divider orientation.
+
+```tsx
+<Divider orientation="horizontal" /> {/* default */}
+<Divider orientation="vertical" />
+
+{/* responsive orientation */}
+<Divider orientation={{ xs: 'horizontal', sm: 'vertical' }} />
+```
+
+### variant
+
+Sets the divider style.
+
+```tsx
+<Divider variant="solid" />    {/* default - solid line */}
+<Divider variant="plain" />    {/* plain style */}
+<Divider variant="soft" />     {/* soft style */}
+```
+
+### color
+
+Sets the divider color.
+
+```tsx
+<Divider color="neutral" />    {/* default */}
+<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>
+
+  <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>
+  {/* activity list */}
+</Sheet>
+```
+
+### Modal Content
+
+```tsx
+<Modal open={open}>
+  <Sheet variant="outlined" sx={{ p: 4, borderRadius: 'md' }}>
+    <Typography level="title-lg">설정</Typography>
+
+    <Divider sx={{ my: 2 }} />
 
-function SectionedForm() {
-  return (
     <Stack spacing={2}>
-      <Typography level="title-md">Personal Info</Typography>
       <FormControl>
-        <FormLabel>Name</FormLabel>
-        <Input />
+        <FormLabel>알림 설정</FormLabel>
+        <Switch />
       </FormControl>
+
       <FormControl>
-        <FormLabel>Email</FormLabel>
-        <Input type="email" />
+        <FormLabel>테마 설정</FormLabel>
+        <Select defaultValue="light">
+          <Option value="light">Light</Option>
+          <Option value="dark">Dark</Option>
+        </Select>
       </FormControl>
+    </Stack>
 
-      <Divider sx={{ my: 3 }}>Additional Info</Divider>
+    <Divider sx={{ my: 3 }} />
 
-      <FormControl>
-        <FormLabel>Company</FormLabel>
-        <Input />
-      </FormControl>
+    <Stack direction="row" spacing={2} justifyContent="flex-end">
+      <Button variant="outlined" onClick={handleClose}>
+        취소
+      </Button>
+      <Button onClick={handleSave}>저장</Button>
     </Stack>
-  );
-}
+  </Sheet>
+</Modal>
 ```
 
-### Login Separator
+## Props and Customization
 
-```tsx
-import { Divider, Stack, Button, Typography } from '@ceed/cds';
+### Key Props
 
-function LoginOptions() {
-  return (
-    <Stack spacing={2} sx={{ maxWidth: 400 }}>
-      <Button fullWidth>Sign in with Email</Button>
+| Prop          | Type                         | Default        | Description                                            |
+| ------------- | ---------------------------- | -------------- | ------------------------------------------------------ |
+| `children`    | `ReactNode`                  | -              | Optional content rendered in the center of the divider |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Divider direction                                      |
+| `component`   | `ElementType`                | `'hr'`         | Root element type                                      |
+| `sx`          | `SxProps`                    | -              | Custom styles                                          |
 
-      <Divider>or</Divider>
+> **Note**: Divider also accepts all Joy UI Divider props.
 
-      <Button fullWidth variant="outlined">Sign in with Google</Button>
-      <Button fullWidth variant="outlined">Sign in with GitHub</Button>
-    </Stack>
-  );
-}
-```
+## Best Practices
 
-### Dashboard Section Separator
+1. **Use appropriate spacing**: Leave enough space above and below the divider so content is clearly separated.
 
-```tsx
-import { Divider, Sheet, Typography, Stack } from '@ceed/cds';
+2. **Separate content meaningfully**: Group logically related content together and use dividers to split sections.
 
-function Dashboard() {
-  return (
-    <Sheet variant="outlined" sx={{ p: 3 }}>
-      <Typography level="title-lg">Dashboard</Typography>
+3. **Avoid overuse**: Too many dividers can make the interface feel cluttered.
 
-      <Divider sx={{ my: 2 }} />
+4. **Using vertical dividers**: When using a vertical divider, explicitly define the height of the parent container.
 
-      <Typography level="title-md">Recent Activity</Typography>
-      {/* Activity list */}
+5. **Consider responsive behavior**: On mobile, a vertical divider may need to switch to horizontal.
 
-      <Divider sx={{ my: 2 }} />
+6. **Keep colors consistent**: Use consistent divider colors and styles throughout the project.
 
-      <Typography level="title-md">Statistics</Typography>
-      {/* Stats content */}
-    </Sheet>
-  );
-}
+7. **Consider accessibility**:
+   - Dividers are purely visual separators, so screen readers typically ignore them
+   - If a semantic separation is needed, use appropriate HTML sectioning elements as well
+
+## Responsive Behavior
+
+Divider supports responsive values for all 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 },
+  }}
+/>
 ```
 
-## Best Practices
+## Motion Support
+
+Divider supports Framer Motion:
 
-- **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.
+```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.
+### ✅ Good Use Cases
 
-- **Use responsive orientation for adaptive layouts.** When a row layout collapses to a column on mobile, switch the divider orientation accordingly using responsive values.
+- **Separate list items**: When you need to clearly divide items in a long list
+- **Separate form sections**: When grouping related fields into sections
+- **Separate content inside cards**: When distinguishing different kinds of information within a card
+- **Navigation menus**: When visually separating menu groups
+- **Dashboard sections**: When dividing widgets or sections in a dashboard
 
-- **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.
+### ❌ Cases Where It May Not Be Appropriate
 
-## Accessibility
+- **When simple spacing is enough**: Avoid using dividers excessively
+- **When other separators already exist**: If content is already separated by color, background, borders, or similar cues, a divider may be unnecessary
+- **For very short content**: A divider can feel excessive for content that is only one or two lines long
 
-- 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 is a useful tool for clarifying content structure and improving readability. When used appropriately, it helps create interfaces that make information easier to understand.

package/dist/components/surfaces/Sheet.md

@@ -685,6 +685,21 @@ function ClickableCard({ title, description, onClick }) {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop             | Type                                                           | Default     | Description                   |
+| ---------------- | -------------------------------------------------------------- | ----------- | ----------------------------- |
+| `children`       | `ReactNode`                                                    | -           | Sheet content                 |
+| `variant`        | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'plain'`   | Visual style                  |
+| `color`          | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'` | Color scheme                  |
+| `invertedColors` | `boolean`                                                      | `false`     | Invert child component colors |
+| `component`      | `ElementType`                                                  | `'div'`     | Root element type             |
+| `sx`             | `SxProps`                                                      | -           | Custom styles                 |
+
+> **Note**: Sheet also accepts all Joy UI Sheet props.
+
 ## Best Practices
 
 - **Choose the right variant for the context.**