# 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/cds';

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는 복잡한 레이아웃을 구현하는 강력한 도구입니다. 반응형 디자인과 일관된 간격을 통해 사용자 경험을 향상시킬 수 있습니다.
