@ceed/ads 1.23.3 → 1.23.5

package/dist/components/surfaces/Sheet.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-Sheet는 콘텐츠를 담는 표면(surface) 컴포넌트입니다. 카드, 패널, 대화상자 등 다양한 UI 요소를 만드는 기반이 되며, 시각적으로 콘텐츠를 그룹화하고 구분하는 역할을 합니다. 다양한 variant와 color 조합을 통해 용도에 맞는 스타일을 적용할 수 있습니다.
+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.
 
 ```tsx
 <Sheet {...args} sx={{
@@ -34,58 +36,18 @@ import { Sheet } from '@ceed/ads';
 function MyComponent() {
   return (
     <Sheet variant="outlined" sx={{ p: 3, borderRadius: 'md' }}>
-      <Typography level="title-md">시트 제목</Typography>
+      <Typography level="title-md">Sheet Title</Typography>
       <Typography level="body-md">
-        시트 안의 콘텐츠가 들어갑니다.
+        Content goes inside the sheet.
       </Typography>
     </Sheet>
   );
 }
 ```
 
-## Examples
-
-### Basic Usage
-
-가장 기본적인 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
+## Variants
 
-다양한 스타일 변형을 제공합니다.
+Sheet supports four visual variants to convey different levels of emphasis.
 
 ```tsx
 <div style={{
@@ -152,9 +114,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={{
@@ -199,9 +161,47 @@ Plain
 </div>
 ```
 
-### User Profile Card
+## 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
 
-사용자 프로필을 표시하는 카드 예제입니다.
+Sheet can be composed with other components to create rich profile cards.
 
 ```tsx
 <Sheet variant="outlined" sx={{
@@ -256,9 +256,9 @@ Plain
 </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 @@ Plain
 </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 @@ Plain
 </Sheet>
 ```
 
-### Stats Cards
+## Stats Cards
 
-통계 정보를 표시하는 카드들입니다.
+Multiple Sheet instances arranged side by side make effective dashboard stat widgets.
 
 ```tsx
 <div style={{
@@ -440,9 +440,9 @@ Plain
 </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 @@ Plain
 </Sheet>
 ```
 
-### Nested Sheets
+## Nested Sheets
 
-시트 안에 다른 시트들을 중첩한 예제입니다.
+Sheets can be nested to create layered dashboard layouts with distinct visual sections.
 
 ```tsx
 <Sheet variant="outlined" sx={{
@@ -599,302 +599,119 @@ Plain
 </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
 
-### Profile Cards
+### Dashboard Stat Widget
 
 ```tsx
-<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>
-
-  <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>
-```
-
-### Dashboard Cards
-
-```tsx
-<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>
-```
-
-### Content Cards
+import { Sheet, Typography, Stack } from '@ceed/ads';
 
-```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>
+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>
+  );
+}
 ```
 
-### Form Containers
+### Alert Banner
 
 ```tsx
-<Sheet variant="outlined" sx={{ maxWidth: 500, borderRadius: 'lg', p: 4 }}>
-  <Typography level="title-lg" sx={{ mb: 3 }}>
-    로그인
-  </Typography>
-
-  <Stack spacing={2}>
-    <FormControl>
-      <FormLabel>이메일</FormLabel>
-      <Input type="email" />
-    </FormControl>
-
-    <FormControl>
-      <FormLabel>비밀번호</FormLabel>
-      <Input type="password" />
-    </FormControl>
+import { Sheet, Typography, Stack, Button } from '@ceed/ads';
+import WarningIcon from '@mui/icons-material/Warning';
 
-    <Button fullWidth>로그인</Button>
-  </Stack>
-</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>
+  );
+}
 ```
 
-### Modal Content
+### Content Card with Hover Effect
 
 ```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
+import { Sheet, Typography, Stack } from '@ceed/ads';
 
-```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>
+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>
+  );
+}
 ```
 
 ## Best Practices
 
-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
+- **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
 
-```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>
-```
+- **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
 
-### Interactive States
+- **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.
 
-```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>
-```
+- **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.
 
-### With Animation (Framer Motion)
+- **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.
 
-```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>
-```
+## Accessibility
 
-Sheet는 유연하고 강력한 표면 컴포넌트로, 다양한 UI 패턴을 구현하는 기초가 됩니다. 적절한 variant와 색상 조합을 통해 일관성 있고 아름다운 인터페이스를 만들 수 있습니다.
+- 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.