@ceed/ads 1.13.4 → 1.15.0-next.2

package/dist/components/layout/Grid.md

@@ -0,0 +1,728 @@
+# Grid
+
+## Introduction
+
+Grid 컴포넌트는 CSS Grid를 기반으로 한 강력한 레이아웃 시스템입니다. 12열 그리드 시스템을 사용하여 반응형 레이아웃을 쉽게 구현할 수 있으며, 다양한 브레이크포인트에서 다른 레이아웃을 적용할 수 있습니다. 복잡한 대시보드, 제품 카탈로그, 카드 레이아웃 등 다양한 용도로 활용할 수 있습니다.
+
+```tsx
+<Grid container spacing={args.spacing}>
+  <GridItem xs={6}>
+    <Typography>Item 1 (xs=6)</Typography>
+  </GridItem>
+  <GridItem xs={6}>
+    <Typography>Item 2 (xs=6)</Typography>
+  </GridItem>
+  <GridItem xs={4}>
+    <Typography>Item 3 (xs=4)</Typography>
+  </GridItem>
+  <GridItem xs={8}>
+    <Typography>Item 4 (xs=8)</Typography>
+  </GridItem>
+</Grid>
+```
+
+| Field     | Description       | Default |
+| --------- | ----------------- | ------- |
+| container | Grid 컨테이너 여부      | true    |
+| spacing   | 그리드 간격            | 2       |
+| xs        | xs 브레이크포인트에서의 열 수 | —       |
+| sm        | sm 브레이크포인트에서의 열 수 | —       |
+| md        | md 브레이크포인트에서의 열 수 | —       |
+| lg        | lg 브레이크포인트에서의 열 수 | —       |
+| xl        | xl 브레이크포인트에서의 열 수 | —       |
+
+## Usage
+
+```tsx
+import { Grid } from '@ceed/ads';
+
+function MyComponent() {
+  return (
+    <Grid container spacing={2}>
+      <Grid item xs={12} sm={6} md={4}>
+        첫 번째 아이템
+      </Grid>
+      <Grid item xs={12} sm={6} md={4}>
+        두 번째 아이템
+      </Grid>
+      <Grid item xs={12} sm={6} md={4}>
+        세 번째 아이템
+      </Grid>
+    </Grid>
+  );
+}
+```
+
+## Examples
+
+### Basic Usage
+
+12열 그리드 시스템의 기본 사용법입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  flexDirection: 'column',
+  gap: '2rem'
+}}>
+<div>
+  <Typography level="title-md" sx={{
+    mb: 2
+  }}>
+  12열 그리드 시스템
+</Typography>
+<Grid container spacing={2}>
+  <GridItem xs={12}>xs=12</GridItem>
+  <GridItem xs={6}>xs=6</GridItem>
+  <GridItem xs={6}>xs=6</GridItem>
+  <GridItem xs={4}>xs=4</GridItem>
+  <GridItem xs={4}>xs=4</GridItem>
+  <GridItem xs={4}>xs=4</GridItem>
+  <GridItem xs={3}>xs=3</GridItem>
+  <GridItem xs={3}>xs=3</GridItem>
+  <GridItem xs={3}>xs=3</GridItem>
+  <GridItem xs={3}>xs=3</GridItem>
+</Grid>
+</div>
+</div>
+```
+
+### Responsive Grid
+
+다양한 화면 크기에서 다른 레이아웃을 적용하는 반응형 그리드입니다.
+
+```tsx
+<div>
+  <Typography level="title-md" sx={{
+    mb: 2
+  }}>
+  반응형 그리드 (브라우저 크기를 조절해보세요)
+</Typography>
+<Grid container spacing={2}>
+  <GridItem xs={12} sm={6} md={4} lg={3}>
+    <div>
+      <Typography level="body-xs">xs=12</Typography>
+      <Typography level="body-xs">sm=6</Typography>
+      <Typography level="body-xs">md=4</Typography>
+      <Typography level="body-xs">lg=3</Typography>
+    </div>
+  </GridItem>
+  <GridItem xs={12} sm={6} md={4} lg={3}>
+    <div>
+      <Typography level="body-xs">xs=12</Typography>
+      <Typography level="body-xs">sm=6</Typography>
+      <Typography level="body-xs">md=4</Typography>
+      <Typography level="body-xs">lg=3</Typography>
+    </div>
+  </GridItem>
+  <GridItem xs={12} sm={6} md={4} lg={3}>
+    <div>
+      <Typography level="body-xs">xs=12</Typography>
+      <Typography level="body-xs">sm=6</Typography>
+      <Typography level="body-xs">md=4</Typography>
+      <Typography level="body-xs">lg=3</Typography>
+    </div>
+  </GridItem>
+  <GridItem xs={12} sm={6} md={4} lg={3}>
+    <div>
+      <Typography level="body-xs">xs=12</Typography>
+      <Typography level="body-xs">sm=6</Typography>
+      <Typography level="body-xs">md=4</Typography>
+      <Typography level="body-xs">lg=3</Typography>
+    </div>
+  </GridItem>
+</Grid>
+</div>
+```
+
+### Different Spacing
+
+다양한 간격을 적용한 그리드 레이아웃입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  flexDirection: 'column',
+  gap: '3rem'
+}}>
+<div>
+  <Typography level="title-sm" sx={{
+    mb: 1
+  }}>
+  간격 없음 (spacing=0)
+</Typography>
+<Grid container spacing={0}>
+  <GridItem xs={4}>Item 1</GridItem>
+  <GridItem xs={4}>Item 2</GridItem>
+  <GridItem xs={4}>Item 3</GridItem>
+</Grid>
+</div>
+
+<div>
+  <Typography level="title-sm" sx={{
+    mb: 1
+  }}>
+  작은 간격 (spacing=1)
+</Typography>
+<Grid container spacing={1}>
+  <GridItem xs={4}>Item 1</GridItem>
+  <GridItem xs={4}>Item 2</GridItem>
+  <GridItem xs={4}>Item 3</GridItem>
+</Grid>
+</div>
+
+<div>
+  <Typography level="title-sm" sx={{
+    mb: 1
+  }}>
+  중간 간격 (spacing=2)
+</Typography>
+<Grid container spacing={2}>
+  <GridItem xs={4}>Item 1</GridItem>
+  <GridItem xs={4}>Item 2</GridItem>
+  <GridItem xs={4}>Item 3</GridItem>
+</Grid>
+</div>
+
+<div>
+  <Typography level="title-sm" sx={{
+    mb: 1
+  }}>
+  큰 간격 (spacing=4)
+</Typography>
+<Grid container spacing={4}>
+  <GridItem xs={4}>Item 1</GridItem>
+  <GridItem xs={4}>Item 2</GridItem>
+  <GridItem xs={4}>Item 3</GridItem>
+</Grid>
+</div>
+</div>
+```
+
+### Nested Grid
+
+그리드 안에 또 다른 그리드를 중첩하여 사용할 수 있습니다.
+
+```tsx
+<div>
+  <Typography level="title-md" sx={{
+    mb: 2
+  }}>
+  중첩된 그리드
+</Typography>
+<Grid container spacing={2}>
+  <Grid xs={12} md={8}>
+    <Box sx={{
+      p: 2,
+      bgcolor: 'success.50',
+      borderRadius: 'md',
+      minHeight: 200
+    }}>
+    <Typography level="title-sm" sx={{
+      mb: 2
+    }}>
+    메인 콘텐츠 영역
+  </Typography>
+  <Grid container spacing={1}>
+    <GridItem xs={6}>
+      <Typography level="body-xs">중첩 아이템 1</Typography>
+    </GridItem>
+    <GridItem xs={6}>
+      <Typography level="body-xs">중첩 아이템 2</Typography>
+    </GridItem>
+    <GridItem xs={12}>
+      <Typography level="body-xs">중첩 아이템 3</Typography>
+    </GridItem>
+  </Grid>
+</Box>
+</Grid>
+
+<Grid xs={12} md={4}>
+  <Box sx={{
+    p: 2,
+    bgcolor: 'warning.50',
+    borderRadius: 'md',
+    minHeight: 200
+  }}>
+  <Typography level="title-sm" sx={{
+    mb: 2
+  }}>
+  사이드바
+</Typography>
+<Grid container spacing={1}>
+  <GridItem xs={12}>
+    <Typography level="body-xs">사이드바 아이템 1</Typography>
+  </GridItem>
+  <GridItem xs={12}>
+    <Typography level="body-xs">사이드바 아이템 2</Typography>
+  </GridItem>
+</Grid>
+</Box>
+</Grid>
+</Grid>
+</div>
+```
+
+### Auto Layout
+
+자동 레이아웃을 사용한 그리드입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  flexDirection: 'column',
+  gap: '2rem'
+}}>
+<div>
+  <Typography level="title-sm" sx={{
+    mb: 1
+  }}>
+  자동 레이아웃 - 동일한 너비
+</Typography>
+<Grid container spacing={2}>
+  <GridItem xs>자동 너비 1</GridItem>
+  <GridItem xs>자동 너비 2</GridItem>
+  <GridItem xs>자동 너비 3</GridItem>
+</Grid>
+</div>
+
+<div>
+  <Typography level="title-sm" sx={{
+    mb: 1
+  }}>
+  자동 레이아웃 - 내용에 따른 너비
+</Typography>
+<Grid container spacing={2}>
+  <GridItem xs="auto">
+    <Typography>짧은 내용</Typography>
+  </GridItem>
+  <GridItem xs>
+    <Typography>남은 공간을 모두 차지하는 긴 내용</Typography>
+  </GridItem>
+  <GridItem xs="auto">
+    <Typography>또 다른 짧은 내용</Typography>
+  </GridItem>
+</Grid>
+</div>
+</div>
+```
+
+### Complex Layouts
+
+실제 사용 사례를 보여주는 복잡한 레이아웃 예제입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  flexDirection: 'column',
+  gap: '3rem'
+}}>
+{/* Dashboard Layout */}
+<div>
+  <Typography level="title-md" sx={{
+    mb: 2
+  }}>
+  대시보드 레이아웃
+</Typography>
+<Grid container spacing={2}>
+  {/* Header */}
+  <Grid xs={12}>
+    <Box sx={{
+      p: 3,
+      bgcolor: 'primary.100',
+      borderRadius: 'md',
+      textAlign: 'center'
+    }}>
+    <Typography level="title-lg">대시보드 헤더</Typography>
+  </Box>
+</Grid>
+
+{/* Stats Cards */}
+<GridItem xs={12} sm={6} lg={3}>
+  <div>
+    <Typography level="title-sm">총 사용자</Typography>
+    <Typography level="h2">1,234</Typography>
+  </div>
+</GridItem>
+<GridItem xs={12} sm={6} lg={3}>
+  <div>
+    <Typography level="title-sm">매출</Typography>
+    <Typography level="h2">₩5.6M</Typography>
+  </div>
+</GridItem>
+<GridItem xs={12} sm={6} lg={3}>
+  <div>
+    <Typography level="title-sm">주문</Typography>
+    <Typography level="h2">789</Typography>
+  </div>
+</GridItem>
+<GridItem xs={12} sm={6} lg={3}>
+  <div>
+    <Typography level="title-sm">전환율</Typography>
+    <Typography level="h2">3.2%</Typography>
+  </div>
+</GridItem>
+
+{/* Main Content */}
+<Grid xs={12} lg={8}>
+  <Box sx={{
+    p: 3,
+    bgcolor: 'neutral.50',
+    borderRadius: 'md',
+    minHeight: 300
+  }}>
+  <Typography level="title-md">차트 영역</Typography>
+  <Typography level="body-sm">여기에 차트가 들어갑니다</Typography>
+</Box>
+</Grid>
+
+{/* Sidebar */}
+<Grid xs={12} lg={4}>
+  <Box sx={{
+    p: 3,
+    bgcolor: 'success.50',
+    borderRadius: 'md',
+    minHeight: 300
+  }}>
+  <Typography level="title-md">최근 활동</Typography>
+  <Typography level="body-sm">활동 목록이 여기 표시됩니다</Typography>
+</Box>
+</Grid>
+</Grid>
+</div>
+
+{/* Product Grid */}
+<div>
+  <Typography level="title-md" sx={{
+    mb: 2
+  }}>
+  제품 그리드
+</Typography>
+<Grid container spacing={2}>
+  {[1, 2, 3, 4, 5, 6].map(item => <Grid key={item} xs={12} sm={6} md={4} lg={2}>
+  <Box sx={{
+    p: 2,
+    bgcolor: 'background.body',
+    border: '1px solid',
+    borderColor: 'divider',
+    borderRadius: 'md',
+    textAlign: 'center'
+  }}>
+  <Box sx={{
+    width: '100%',
+    height: 80,
+    bgcolor: 'neutral.100',
+    borderRadius: 'sm',
+    mb: 1,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center'
+  }}>
+  <Typography level="body-xs">제품 {item}</Typography>
+</Box>
+<Typography level="body-sm">제품명</Typography>
+<Typography level="body-xs" sx={{
+  color: 'text.secondary'
+}}>
+₩10,000
+</Typography>
+</Box>
+</Grid>)}
+</Grid>
+</div>
+</div>
+```
+
+### Breakpoint Demo
+
+각 브레이크포인트에서 어떻게 동작하는지 보여주는 예제입니다.
+
+```tsx
+<div>
+  <Typography level="title-md" sx={{
+    mb: 2
+  }}>
+  브레이크포인트 데모 - 각 화면 크기에서 다른 레이아웃
+</Typography>
+
+<Box sx={{
+  mb: 2
+}}>
+<Typography level="body-sm" sx={{
+  color: 'text.secondary'
+}}>
+• xs (0px+): 모든 아이템이 한 줄로
+<br />
+• sm (600px+): 2개씩 배치
+<br />
+• md (900px+): 3개씩 배치
+<br />• lg (1200px+): 4개씩 배치
+</Typography>
+</Box>
+
+<Grid container spacing={2}>
+  <GridItem xs={12} sm={6} md={4} lg={3}>
+    <Typography level="body-sm">첫 번째 아이템</Typography>
+  </GridItem>
+  <GridItem xs={12} sm={6} md={4} lg={3}>
+    <Typography level="body-sm">두 번째 아이템</Typography>
+  </GridItem>
+  <GridItem xs={12} sm={6} md={4} lg={3}>
+    <Typography level="body-sm">세 번째 아이템</Typography>
+  </GridItem>
+  <GridItem xs={12} sm={6} md={4} lg={3}>
+    <Typography level="body-sm">네 번째 아이템</Typography>
+  </GridItem>
+  <GridItem xs={12} sm={6} md={4} lg={3}>
+    <Typography level="body-sm">다섯 번째 아이템</Typography>
+  </GridItem>
+  <GridItem xs={12} sm={6} md={4} lg={3}>
+    <Typography level="body-sm">여섯 번째 아이템</Typography>
+  </GridItem>
+  <GridItem xs={12} sm={6} md={4} lg={3}>
+    <Typography level="body-sm">일곱 번째 아이템</Typography>
+  </GridItem>
+  <GridItem xs={12} sm={6} md={4} lg={3}>
+    <Typography level="body-sm">여덟 번째 아이템</Typography>
+  </GridItem>
+</Grid>
+</div>
+```
+
+## Grid System
+
+### 12열 시스템
+
+Grid는 12열 시스템을 기반으로 합니다. 각 아이템은 1-12열을 차지할 수 있습니다.
+
+```tsx
+<Grid container spacing={2}>
+  <Grid item xs={12}>전체 너비 (12/12)</Grid>
+  <Grid item xs={6}>절반 너비 (6/12)</Grid>
+  <Grid item xs={6}>절반 너비 (6/12)</Grid>
+  <Grid item xs={4}>3분의 1 너비 (4/12)</Grid>
+  <Grid item xs={4}>3분의 1 너비 (4/12)</Grid>
+  <Grid item xs={4}>3분의 1 너비 (4/12)</Grid>
+</Grid>
+```
+
+### Container & Item
+
+- `container`: Grid 컨테이너를 만들 때 사용
+- `item`: Grid 아이템을 만들 때 사용
+- 한 컴포넌트가 동시에 container와 item이 될 수 있습니다 (중첩 그리드)
+
+## Breakpoints
+
+Grid는 다음 브레이크포인트를 지원합니다:
+
+| 브레이크포인트 | 크기      | 설명                |
+| ------- | ------- | ----------------- |
+| `xs`    | 0px+    | 모바일 (세로)          |
+| `sm`    | 600px+  | 모바일 (가로) / 작은 태블릿 |
+| `md`    | 900px+  | 태블릿               |
+| `lg`    | 1200px+ | 데스크톱              |
+| `xl`    | 1536px+ | 큰 데스크톱            |
+
+### 반응형 사용법
+
+```tsx
+<Grid container spacing={2}>
+  <Grid item xs={12} sm={6} md={4} lg={3}>
+    {/*
+      xs: 100% (12/12) - 모바일에서 전체 너비
+      sm: 50% (6/12)   - 작은 화면에서 절반 너비
+      md: 33% (4/12)   - 태블릿에서 3분의 1 너비
+      lg: 25% (3/12)   - 데스크톱에서 4분의 1 너비
+    */}
+    반응형 아이템
+  </Grid>
+</Grid>
+```
+
+## Spacing
+
+`spacing` prop을 사용하여 그리드 아이템 간의 간격을 조절할 수 있습니다.
+
+| 값   | 크기   | 설명          |
+| --- | ---- | ----------- |
+| `0` | 0px  | 간격 없음       |
+| `1` | 8px  | 아주 작은 간격    |
+| `2` | 16px | 작은 간격 (기본값) |
+| `3` | 24px | 중간 간격       |
+| `4` | 32px | 큰 간격        |
+| `5` | 40px | 아주 큰 간격     |
+| `6` | 48px | 최대 간격       |
+
+## Auto Layout
+
+열 수를 명시하지 않고 자동으로 배치되도록 할 수 있습니다:
+
+```tsx
+<Grid container spacing={2}>
+  <Grid item xs>자동 너비 1</Grid>
+  <Grid item xs>자동 너비 2</Grid>
+  <Grid item xs>자동 너비 3</Grid>
+</Grid>
+
+<Grid container spacing={2}>
+  <Grid item xs="auto">내용에 맞춰 자동 크기</Grid>
+  <Grid item xs>남은 공간 모두 차지</Grid>
+  <Grid item xs="auto">내용에 맞춰 자동 크기</Grid>
+</Grid>
+```
+
+## Common Use Cases
+
+### Card Layout
+
+```tsx
+<Grid container spacing={3}>
+  {products.map((product) => (
+    <Grid key={product.id} item xs={12} sm={6} md={4} lg={3}>
+      <Card>
+        <CardContent>
+          <Typography level="title-md">{product.name}</Typography>
+          <Typography level="body-sm">{product.price}</Typography>
+        </CardContent>
+      </Card>
+    </Grid>
+  ))}
+</Grid>
+```
+
+### Dashboard Layout
+
+```tsx
+<Grid container spacing={2}>
+  {/* Header */}
+  <Grid item xs={12}>
+    <Paper sx={{ p: 2 }}>Dashboard Header</Paper>
+  </Grid>
+
+  {/* Stats */}
+  <Grid item xs={12} sm={6} md={3}>
+    <StatCard title="Users" value="1,234" />
+  </Grid>
+  <Grid item xs={12} sm={6} md={3}>
+    <StatCard title="Revenue" value="$5.6M" />
+  </Grid>
+  <Grid item xs={12} sm={6} md={3}>
+    <StatCard title="Orders" value="789" />
+  </Grid>
+  <Grid item xs={12} sm={6} md={3}>
+    <StatCard title="Growth" value="+12%" />
+  </Grid>
+
+  {/* Main Content */}
+  <Grid item xs={12} lg={8}>
+    <Paper sx={{ p: 2, minHeight: 400 }}>Chart Area</Paper>
+  </Grid>
+
+  {/* Sidebar */}
+  <Grid item xs={12} lg={4}>
+    <Paper sx={{ p: 2, minHeight: 400 }}>Recent Activity</Paper>
+  </Grid>
+</Grid>
+```
+
+### Form Layout
+
+```tsx
+<Grid container spacing={2}>
+  <Grid item xs={12} md={6}>
+    <FormControl fullWidth>
+      <FormLabel>First Name</FormLabel>
+      <Input placeholder="Enter first name" />
+    </FormControl>
+  </Grid>
+
+  <Grid item xs={12} md={6}>
+    <FormControl fullWidth>
+      <FormLabel>Last Name</FormLabel>
+      <Input placeholder="Enter last name" />
+    </FormControl>
+  </Grid>
+
+  <Grid item xs={12}>
+    <FormControl fullWidth>
+      <FormLabel>Email</FormLabel>
+      <Input type="email" placeholder="Enter email" />
+    </FormControl>
+  </Grid>
+
+  <Grid item xs={12}>
+    <Button type="submit" fullWidth>Submit</Button>
+  </Grid>
+</Grid>
+```
+
+### Image Gallery
+
+```tsx
+<Grid container spacing={1}>
+  {images.map((image, index) => (
+    <Grid key={index} item xs={6} sm={4} md={3} lg={2}>
+      <Box
+        sx={{
+          position: 'relative',
+          paddingTop: '100%', // 1:1 비율 유지
+          overflow: 'hidden',
+          borderRadius: 'sm',
+        }}
+      >
+        <img
+          src={image.src}
+          alt={image.alt}
+          style={{
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            width: '100%',
+            height: '100%',
+            objectFit: 'cover',
+          }}
+        />
+      </Box>
+    </Grid>
+  ))}
+</Grid>
+```
+
+## Best Practices
+
+1. **의미 있는 구조**: Grid를 사용할 때 HTML의 의미구조를 고려하여 적절한 요소를 선택하세요.
+
+2. **반응형 우선 설계**: 모바일부터 시작하여 큰 화면으로 확장하는 방식으로 설계하세요.
+
+3. **일관된 간격**: 프로젝트 전반에서 일관된 spacing 값을 사용하세요.
+
+4. **성능 최적화**:
+   - 불필요하게 깊은 중첩은 피하세요
+   - 많은 아이템이 있을 때는 가상화를 고려하세요
+
+5. **접근성**:
+   - 적절한 시맨틱 태그를 사용하세요
+   - 키보드 탐색이 논리적으로 이뤄지도록 배치하세요
+
+6. **콘텐츠 우선**: 그리드가 콘텐츠를 억지로 맞추는 것이 아니라 콘텐츠에 맞춰 조정되도록 하세요.
+
+7. **디버깅**: 개발 중에는 Grid 아이템에 배경색을 적용해 레이아웃을 쉽게 확인하세요.
+
+## Troubleshooting
+
+### 흔한 문제들
+
+1. **아이템이 예상과 다르게 배치됨**
+   - 12를 넘지 않도록 열 수를 확인하세요
+   - container와 item props가 올바르게 설정되었는지 확인하세요
+
+2. **간격이 적용되지 않음**
+   - container에 spacing prop이 설정되었는지 확인하세요
+   - 자식 요소들이 Grid item으로 감싸져 있는지 확인하세요
+
+3. **반응형이 동작하지 않음**
+   - 브레이크포인트 값이 올바른지 확인하세요
+   - 각 브레이크포인트에서 의도한 합계가 12 이하인지 확인하세요
+
+Grid는 복잡한 레이아웃을 구현하는 강력한 도구입니다. 반응형 디자인과 일관된 간격을 통해 사용자 경험을 향상시킬 수 있습니다.