@ceed/ads 1.29.1 → 1.30.0-next.1

package/dist/components/surfaces/Sheet.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-Sheet is a foundational surface component that serves as a container for grouping and visually separating content. It acts as the building block for creating cards, panels, dialogs, and other elevated UI elements. By combining different `variant` and `color` props, you can tailor the Sheet's appearance to match its purpose -- whether it is a subtle content container, an attention-grabbing notification banner, or a structured form wrapper.
-
-Sheet is built on top of Joy UI's Sheet component and inherits all of its styling capabilities, including support for the `sx` prop for custom styling, responsive design tokens, and Framer Motion animation props.
+Sheet는 콘텐츠를 담는 표면(surface) 컴포넌트입니다. 카드, 패널, 대화상자 등 다양한 UI 요소를 만드는 기반이 되며, 시각적으로 콘텐츠를 그룹화하고 구분하는 역할을 합니다. 다양한 variant와 color 조합을 통해 용도에 맞는 스타일을 적용할 수 있습니다.
 
 ```tsx
 <Sheet {...args} sx={{
@@ -36,18 +34,58 @@ import { Sheet } from '@ceed/ads';
 function MyComponent() {
   return (
     <Sheet variant="outlined" sx={{ p: 3, borderRadius: 'md' }}>
-      <Typography level="title-md">Sheet Title</Typography>
+      <Typography level="title-md">시트 제목</Typography>
       <Typography level="body-md">
-        Content goes inside the sheet.
+        시트 안의 콘텐츠가 들어갑니다.
       </Typography>
     </Sheet>
   );
 }
 ```
 
-## Variants
+## Examples
+
+### Basic Usage
 
-Sheet supports four visual variants to convey different levels of emphasis.
+가장 기본적인 Sheet 사용법입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem',
+  flexWrap: 'wrap'
+}}>
+<Sheet sx={{
+  p: 3,
+  maxWidth: 300,
+  borderRadius: 'md'
+}}>
+<Typography level="title-md" sx={{
+  mb: 1
+}}>
+기본 Sheet
+</Typography>
+<Typography level="body-sm">가장 기본적인 Sheet 컴포넌트입니다.</Typography>
+</Sheet>
+
+<Sheet variant="outlined" sx={{
+  p: 3,
+  maxWidth: 300,
+  borderRadius: 'md'
+}}>
+<Typography level="title-md" sx={{
+  mb: 1
+}}>
+Outlined Sheet
+</Typography>
+<Typography level="body-sm">테두리가 있는 Sheet 컴포넌트입니다.</Typography>
+</Sheet>
+</div>
+```
+
+### Variants
+
+다양한 스타일 변형을 제공합니다.
 
 ```tsx
 <div style={{
@@ -114,9 +152,9 @@ Plain
 </div>
 ```
 
-## Colors
+### Colors
 
-Apply semantic colors to communicate meaning -- use `danger` for errors, `success` for confirmations, `warning` for alerts, and `primary` for highlighted content.
+다양한 색상을 적용할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -161,47 +199,9 @@ Apply semantic colors to communicate meaning -- use `danger` for errors, `succes
 </div>
 ```
 
-## Basic
-
-The simplest form of a Sheet with minimal configuration.
-
-```tsx
-<div style={{
-  display: 'flex',
-  gap: '2rem',
-  flexWrap: 'wrap'
-}}>
-<Sheet sx={{
-  p: 3,
-  maxWidth: 300,
-  borderRadius: 'md'
-}}>
-<Typography level="title-md" sx={{
-  mb: 1
-}}>
-기본 Sheet
-</Typography>
-<Typography level="body-sm">가장 기본적인 Sheet 컴포넌트입니다.</Typography>
-</Sheet>
-
-<Sheet variant="outlined" sx={{
-  p: 3,
-  maxWidth: 300,
-  borderRadius: 'md'
-}}>
-<Typography level="title-md" sx={{
-  mb: 1
-}}>
-Outlined Sheet
-</Typography>
-<Typography level="body-sm">테두리가 있는 Sheet 컴포넌트입니다.</Typography>
-</Sheet>
-</div>
-```
-
-## User Profile Card
+### User Profile Card
 
-Sheet can be composed with other components to create rich profile cards.
+사용자 프로필을 표시하는 카드 예제입니다.
 
 ```tsx
 <Sheet variant="outlined" sx={{
@@ -256,9 +256,9 @@ Sheet can be composed with other components to create rich profile cards.
 </Sheet>
 ```
 
-## Article Card
+### Article Card
 
-Combine Sheet with images, chips, and actions for article-style layouts.
+아티클을 표시하는 복잡한 카드 레이아웃 예제입니다.
 
 ```tsx
 <Sheet variant="outlined" sx={{
@@ -329,9 +329,9 @@ Combine Sheet with images, chips, and actions for article-style layouts.
 </Sheet>
 ```
 
-## Notification Panel
+### Notification Panel
 
-Use `variant="soft"` with a semantic color to create attention-grabbing notification banners.
+알림을 표시하는 패널 예제입니다.
 
 ```tsx
 <Sheet variant="soft" color="primary" sx={{
@@ -362,9 +362,9 @@ Use `variant="soft"` with a semantic color to create attention-grabbing notifica
 </Sheet>
 ```
 
-## Stats Cards
+### Stats Cards
 
-Multiple Sheet instances arranged side by side make effective dashboard stat widgets.
+통계 정보를 표시하는 카드들입니다.
 
 ```tsx
 <div style={{
@@ -440,9 +440,9 @@ Multiple Sheet instances arranged side by side make effective dashboard stat wid
 </div>
 ```
 
-## Form Sheet
+### Form Sheet
 
-Wrap form elements inside a Sheet to create visually contained form sections.
+폼을 담고 있는 시트 예제입니다.
 
 ```tsx
 <Sheet variant="outlined" sx={{
@@ -528,9 +528,9 @@ Wrap form elements inside a Sheet to create visually contained form sections.
 </Sheet>
 ```
 
-## Nested Sheets
+### Nested Sheets
 
-Sheets can be nested to create layered dashboard layouts with distinct visual sections.
+시트 안에 다른 시트들을 중첩한 예제입니다.
 
 ```tsx
 <Sheet variant="outlined" sx={{
@@ -585,7 +585,7 @@ Sheets can be nested to create layered dashboard layouts with distinct visual se
   <Typography level="title-md">최근 활동</Typography>
 
   <Stack spacing={1}>
-    {['새로운 사용자가 가입했습니다', '프로젝트가 완료되었습니다', '댓글이 등록되었습니다'].map(activity => <Box key={activity} sx={{
+    {['새로운 사용자가 가입했습니다', '프로젝트가 완료되었습니다', '댓글이 등록되었습니다'].map((activity, index) => <Box key={index} sx={{
       p: 1.5,
       bgcolor: 'background.body',
       borderRadius: 'sm'
@@ -599,119 +599,302 @@ Sheets can be nested to create layered dashboard layouts with distinct visual se
 </Sheet>
 ```
 
+## Variants
+
+Sheet는 4가지 variant를 지원합니다:
+
+### solid
+
+배경색이 채워진 스타일입니다. 강조가 필요한 콘텐츠에 사용합니다.
+
+```tsx
+<Sheet variant="solid" color="primary">
+  강조된 콘텐츠
+</Sheet>
+```
+
+### soft
+
+부드러운 배경색을 가진 스타일입니다. 눈에 띄지만 과하지 않은 강조에 사용합니다.
+
+```tsx
+<Sheet variant="soft" color="success">
+  부드러운 강조
+</Sheet>
+```
+
+### outlined
+
+테두리가 있는 스타일입니다. 가장 일반적으로 사용되는 카드 스타일입니다.
+
+```tsx
+<Sheet variant="outlined">
+  기본 카드 스타일
+</Sheet>
+```
+
+### plain
+
+배경이나 테두리가 없는 평면 스타일입니다. 미니멀한 디자인에 사용합니다.
+
+```tsx
+<Sheet variant="plain">
+  미니멀한 스타일
+</Sheet>
+```
+
+## Colors
+
+다양한 색상 테마를 적용할 수 있습니다:
+
+- **primary**: 주요 작업이나 중요한 정보
+- **neutral**: 일반적인 콘텐츠 (기본값)
+- **danger**: 오류나 경고 상황
+- **success**: 성공이나 긍정적인 결과
+- **warning**: 주의사항이나 중요한 알림
+
+```tsx
+<Sheet color="danger" variant="soft">
+  오류 메시지
+</Sheet>
+<Sheet color="success" variant="soft">
+  성공 메시지
+</Sheet>
+```
+
 ## Common Use Cases
 
-### Dashboard Stat Widget
+### Profile Cards
 
 ```tsx
-import { Sheet, Typography, Stack } from '@ceed/ads';
+<Sheet variant="outlined" sx={{ maxWidth: 400, borderRadius: 'lg', p: 3 }}>
+  <Stack direction="row" spacing={2} alignItems="center">
+    <Avatar size="lg" src="/profile.jpg" />
+    <Stack>
+      <Typography level="title-lg">사용자 이름</Typography>
+      <Typography level="body-sm" color="neutral">직책</Typography>
+    </Stack>
+  </Stack>
 
-function StatWidget({ label, value, change }) {
-  return (
-    <Sheet variant="outlined" sx={{ p: 3, borderRadius: 'lg', minWidth: 200 }}>
-      <Stack spacing={1}>
-        <Typography level="body-sm" sx={{ color: 'text.secondary' }}>
-          {label}
-        </Typography>
-        <Typography level="h2" color="primary">
-          {value}
-        </Typography>
-        <Typography
-          level="body-xs"
-          sx={{ color: change > 0 ? 'success.600' : 'danger.600' }}
-        >
-          {change > 0 ? '+' : ''}{change}% from last month
-        </Typography>
-      </Stack>
-    </Sheet>
-  );
-}
+  <Typography level="body-md" sx={{ mt: 2 }}>
+    사용자 소개 텍스트...
+  </Typography>
+
+  <Stack direction="row" spacing={2} sx={{ mt: 3 }}>
+    <Button variant="outlined" fullWidth>팔로우</Button>
+    <Button fullWidth>메시지</Button>
+  </Stack>
+</Sheet>
 ```
 
-### Alert Banner
+### Dashboard Cards
 
 ```tsx
-import { Sheet, Typography, Stack, Button } from '@ceed/ads';
-import WarningIcon from '@mui/icons-material/Warning';
+<Sheet variant="outlined" sx={{ p: 3, borderRadius: 'lg' }}>
+  <Typography level="body-sm" color="neutral">
+    총 매출
+  </Typography>
+  <Typography level="h2" color="primary">
+    ₩1,234,567
+  </Typography>
+  <Typography level="body-xs" color="success">
+    +12% 증가
+  </Typography>
+</Sheet>
+```
 
-function AlertBanner({ message, onDismiss }) {
-  return (
-    <Sheet
-      variant="soft"
-      color="warning"
-      sx={{ borderRadius: 'md', p: 2 }}
-    >
-      <Stack direction="row" alignItems="center" spacing={2}>
-        <WarningIcon />
-        <Typography level="body-md" sx={{ flex: 1 }}>
-          {message}
-        </Typography>
-        <Button size="sm" variant="plain" onClick={onDismiss}>
-          Dismiss
-        </Button>
-      </Stack>
-    </Sheet>
-  );
-}
+### Content Cards
+
+```tsx
+<Sheet variant="outlined" sx={{ borderRadius: 'lg', overflow: 'hidden' }}>
+  <Box sx={{ height: 200, bgcolor: 'primary.100' }}>
+    {/* 이미지나 미디어 콘텐츠 */}
+  </Box>
+
+  <Stack spacing={2} sx={{ p: 3 }}>
+    <Typography level="title-lg">콘텐츠 제목</Typography>
+    <Typography level="body-md">콘텐츠 설명...</Typography>
+
+    <Stack direction="row" justifyContent="space-between">
+      <Typography level="body-sm" color="neutral">
+        2024.01.15
+      </Typography>
+      <Button size="sm">더 보기</Button>
+    </Stack>
+  </Stack>
+</Sheet>
 ```
 
-### Content Card with Hover Effect
+### Form Containers
 
 ```tsx
-import { Sheet, Typography, Stack } from '@ceed/ads';
+<Sheet variant="outlined" sx={{ maxWidth: 500, borderRadius: 'lg', p: 4 }}>
+  <Typography level="title-lg" sx={{ mb: 3 }}>
+    로그인
+  </Typography>
 
-function ClickableCard({ title, description, onClick }) {
-  return (
-    <Sheet
-      variant="outlined"
-      sx={{
-        p: 3,
-        borderRadius: 'lg',
-        cursor: 'pointer',
-        transition: 'all 0.2s',
-        '&:hover': {
-          boxShadow: 'md',
-          transform: 'translateY(-2px)',
-        },
-      }}
-      onClick={onClick}
-    >
-      <Stack spacing={1}>
-        <Typography level="title-lg">{title}</Typography>
-        <Typography level="body-md">{description}</Typography>
-      </Stack>
-    </Sheet>
-  );
-}
+  <Stack spacing={2}>
+    <FormControl>
+      <FormLabel>이메일</FormLabel>
+      <Input type="email" />
+    </FormControl>
+
+    <FormControl>
+      <FormLabel>비밀번호</FormLabel>
+      <Input type="password" />
+    </FormControl>
+
+    <Button fullWidth>로그인</Button>
+  </Stack>
+</Sheet>
+```
+
+### Modal Content
+
+```tsx
+<Sheet
+  variant="outlined"
+  sx={{
+    position: 'fixed',
+    top: '50%',
+    left: '50%',
+    transform: 'translate(-50%, -50%)',
+    borderRadius: 'lg',
+    p: 4,
+    maxWidth: 400,
+    boxShadow: 'lg',
+  }}
+>
+  <Typography level="title-lg" sx={{ mb: 2 }}>
+    확인 필요
+  </Typography>
+  <Typography level="body-md" sx={{ mb: 3 }}>
+    정말로 이 작업을 수행하시겠습니까?
+  </Typography>
+
+  <Stack direction="row" spacing={2} justifyContent="flex-end">
+    <Button variant="outlined">취소</Button>
+    <Button color="danger">삭제</Button>
+  </Stack>
+</Sheet>
+```
+
+### Notification Banners
+
+```tsx
+<Sheet
+  variant="soft"
+  color="warning"
+  sx={{ borderRadius: 'md', p: 2 }}
+>
+  <Stack direction="row" alignItems="center" spacing={2}>
+    <WarningIcon />
+    <Typography level="body-md">
+      시스템 점검이 예정되어 있습니다.
+    </Typography>
+    <Button size="sm" variant="plain">
+      자세히 보기
+    </Button>
+  </Stack>
+</Sheet>
 ```
 
 ## Best Practices
 
-- **Choose the right variant for the context.**
-  - `outlined` for general-purpose cards and panels
-  - `soft` for subtle emphasis or notification banners
-  - `solid` for high-emphasis content that demands attention
-  - `plain` for minimal or nested containers
+1. **적절한 패딩**: 콘텐츠 양에 따라 적절한 패딩을 설정하세요.
+   ```tsx
+   <Sheet sx={{ p: { xs: 2, sm: 3, md: 4 } }}>
+   ```
+
+2. **의미있는 변형 선택**:
+   - `outlined`: 일반적인 카드나 패널
+   - `soft`: 부드러운 강조나 구분
+   - `solid`: 강한 강조나 액션
+   - `plain`: 미니멀하거나 중첩된 콘텐츠
+
+3. **색상의 의미 활용**:
+   - `danger`: 오류, 삭제 등 위험한 작업
+   - `success`: 성공 메시지, 완료 상태
+   - `warning`: 주의사항, 중요 알림
+   - `primary`: 주요 액션, 강조 콘텐츠
+   - `neutral`: 일반 콘텐츠
+
+4. **반응형 고려**:
+   ```tsx
+   <Sheet sx={{
+     maxWidth: { xs: '100%', sm: 400 },
+     borderRadius: { xs: 0, sm: 'lg' },
+     p: { xs: 2, sm: 3 }
+   }}>
+   ```
+
+5. **접근성**:
+   - 적절한 시맨틱 태그와 함께 사용하세요
+   - 충분한 색상 대비를 유지하세요
+   - 키보드 탐색을 고려하세요
+
+6. **성능**:
+   - 그림자나 복잡한 스타일은 필요할 때만 사용하세요
+   - 많은 카드가 있을 때는 가상화를 고려하세요
+
+7. **일관성**:
+   - 프로젝트 전반에서 일관된 borderRadius와 spacing을 사용하세요
+   - 비슷한 콘텐츠에는 동일한 variant를 사용하세요
+
+## Advanced Usage
+
+### Custom Styling
 
-- **Use semantic colors intentionally.**
-  - `danger` for error states and destructive actions
-  - `success` for confirmation messages and positive outcomes
-  - `warning` for caution alerts and important notices
-  - `primary` for highlighted or brand-related content
-  - `neutral` for general, non-semantic content
+```tsx
+<Sheet
+  sx={{
+    background: 'linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%)',
+    border: 0,
+    borderRadius: 3,
+    boxShadow: '0 3px 5px 2px rgba(255, 105, 135, .3)',
+    color: 'white',
+    p: 3,
+  }}
+>
+  커스텀 스타일링
+</Sheet>
+```
 
-- **Maintain consistent spacing.**
-  - Use the `sx` prop with design tokens (`p: 3`, `borderRadius: 'lg'`) rather than arbitrary pixel values to keep layouts consistent across the application.
+### Interactive States
 
-- **Avoid deeply nested Sheets.**
-  - While nesting is supported, more than two levels of nesting can make the visual hierarchy confusing. Consider flattening the structure or using Divider components instead.
+```tsx
+<Sheet
+  variant="outlined"
+  sx={{
+    cursor: 'pointer',
+    transition: 'all 0.2s',
+    '&:hover': {
+      boxShadow: 'md',
+      transform: 'translateY(-2px)',
+    },
+    '&:active': {
+      transform: 'translateY(0)',
+    },
+  }}
+  onClick={() => console.log('clicked')}
+>
+  클릭 가능한 카드
+</Sheet>
+```
 
-- **Prefer composition over complexity.**
-  - Sheet is intentionally a low-level primitive. Compose it with Typography, Stack, Button, and other components rather than overloading the Sheet with custom styling.
+### With Animation (Framer Motion)
 
-## Accessibility
+```tsx
+<Sheet
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.3 }}
+  whileHover={{ scale: 1.02 }}
+  variant="outlined"
+  sx={{ p: 3 }}
+>
+  애니메이션 카드
+</Sheet>
+```
 
-- Sheet renders as a `<div>` by default. When the content has a semantic meaning (e.g., a section or article), use the `component` prop to render an appropriate HTML element such as `<section>` or `<article>`.
-- When a Sheet is interactive (clickable), ensure it has a proper `role` attribute (e.g., `role="button"`) and supports keyboard interaction via `tabIndex` and `onKeyDown`.
-- Maintain sufficient color contrast between the Sheet background and its text content, especially when using `variant="solid"` with colored backgrounds.
-- Avoid relying solely on color to convey information. Pair color indicators with icons or text labels for users with color vision deficiencies.
+Sheet는 유연하고 강력한 표면 컴포넌트로, 다양한 UI 패턴을 구현하는 기초가 됩니다. 적절한 variant와 색상 조합을 통해 일관성 있고 아름다운 인터페이스를 만들 수 있습니다.