# Box

## Introduction

Box는 가장 기본적이고 중요한 레이아웃 컴포넌트입니다. 다른 컴포넌트들을 감싸는 범용 컨테이너 역할을 하며, CSS-in-JS를 통해 스타일을 직접 적용할 수 있습니다. Framer Motion이 내장되어 있어 애니메이션 효과도 쉽게 추가할 수 있습니다. 모든 HTML 요소로 변환 가능한 다형성(polymorphic) 컴포넌트이기도 합니다.

```tsx
<Box {...args} sx={{
  width: 200,
  height: 200,
  backgroundColor: 'primary.50',
  border: '2px solid',
  borderColor: 'primary.200',
  borderRadius: 'md',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}}>
<Typography>Box 컴포넌트</Typography>
</Box>
```

| Field     | Description | Default |
| --------- | ----------- | ------- |
| component | HTML 요소 타입  | "div"   |

## Usage

```tsx
import { Box } from '@ceed/ads';

function MyComponent() {
  return (
    <Box
      sx={{
        p: 2,
        bgcolor: 'primary.50',
        borderRadius: 'md',
      }}
    >
      콘텐츠가 들어갑니다
    </Box>
  );
}
```

## Examples

### Basic Usage

가장 기본적인 Box 사용법입니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexWrap: 'wrap'
}}>
<Box sx={{
  p: 2,
  bgcolor: 'background.body',
  border: '1px solid',
  borderColor: 'divider'
}}>
<Typography>기본 Box</Typography>
</Box>

<Box sx={{
  p: 2,
  bgcolor: 'primary.50',
  borderRadius: 'sm'
}}>
<Typography>배경색과 둥근 모서리</Typography>
</Box>

<Box sx={{
  p: 2,
  border: '2px solid',
  borderColor: 'primary.main',
  borderRadius: 'md'
}}>
<Typography>테두리가 있는 Box</Typography>
</Box>
</div>
```

### Colors

다양한 배경색을 적용할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexWrap: 'wrap'
}}>
<Box sx={{
  p: 2,
  bgcolor: 'primary.50',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">Primary</Typography>
</Box>

<Box sx={{
  p: 2,
  bgcolor: 'neutral.50',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">Neutral</Typography>
</Box>

<Box sx={{
  p: 2,
  bgcolor: 'danger.50',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">Danger</Typography>
</Box>

<Box sx={{
  p: 2,
  bgcolor: 'success.50',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">Success</Typography>
</Box>

<Box sx={{
  p: 2,
  bgcolor: 'warning.50',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">Warning</Typography>
</Box>
</div>
```

### Spacing

패딩과 마진을 조절할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  flexDirection: 'column',
  gap: '1rem'
}}>
<Box sx={{
  p: 1,
  bgcolor: 'neutral.100',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">패딩 1 (8px)</Typography>
</Box>

<Box sx={{
  p: 2,
  bgcolor: 'neutral.100',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">패딩 2 (16px)</Typography>
</Box>

<Box sx={{
  p: 3,
  bgcolor: 'neutral.100',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">패딩 3 (24px)</Typography>
</Box>

<Box sx={{
  p: 4,
  bgcolor: 'neutral.100',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">패딩 4 (32px)</Typography>
</Box>

<div style={{
  display: 'flex',
  gap: '1rem',
  marginTop: '2rem'
}}>
<Box sx={{
  m: 1,
  p: 2,
  bgcolor: 'primary.50',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">마진 1</Typography>
</Box>

<Box sx={{
  m: 2,
  p: 2,
  bgcolor: 'primary.50',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">마진 2</Typography>
</Box>

<Box sx={{
  m: 3,
  p: 2,
  bgcolor: 'primary.50',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">마진 3</Typography>
</Box>
</div>
</div>
```

### Border Radius

모서리 둥글기를 다양하게 설정할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexWrap: 'wrap',
  alignItems: 'center'
}}>
<Box sx={{
  width: 100,
  height: 100,
  bgcolor: 'primary.100',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}}>
<Typography level="body-xs">None</Typography>
</Box>

<Box sx={{
  width: 100,
  height: 100,
  bgcolor: 'primary.100',
  borderRadius: 'xs',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}}>
<Typography level="body-xs">XS</Typography>
</Box>

<Box sx={{
  width: 100,
  height: 100,
  bgcolor: 'primary.100',
  borderRadius: 'sm',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}}>
<Typography level="body-xs">SM</Typography>
</Box>

<Box sx={{
  width: 100,
  height: 100,
  bgcolor: 'primary.100',
  borderRadius: 'md',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}}>
<Typography level="body-xs">MD</Typography>
</Box>

<Box sx={{
  width: 100,
  height: 100,
  bgcolor: 'primary.100',
  borderRadius: 'lg',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}}>
<Typography level="body-xs">LG</Typography>
</Box>

<Box sx={{
  width: 100,
  height: 100,
  bgcolor: 'primary.100',
  borderRadius: 'xl',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}}>
<Typography level="body-xs">XL</Typography>
</Box>
</div>
```

### Shadows

그림자 효과를 추가할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  gap: '2rem',
  flexWrap: 'wrap',
  alignItems: 'center',
  padding: '2rem'
}}>
<Box sx={{
  width: 120,
  height: 80,
  bgcolor: 'background.body',
  borderRadius: 'md',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}}>
<Typography level="body-sm">No Shadow</Typography>
</Box>

<Box sx={{
  width: 120,
  height: 80,
  bgcolor: 'background.body',
  borderRadius: 'md',
  boxShadow: 'xs',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}}>
<Typography level="body-sm">XS Shadow</Typography>
</Box>

<Box sx={{
  width: 120,
  height: 80,
  bgcolor: 'background.body',
  borderRadius: 'md',
  boxShadow: 'sm',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}}>
<Typography level="body-sm">SM Shadow</Typography>
</Box>

<Box sx={{
  width: 120,
  height: 80,
  bgcolor: 'background.body',
  borderRadius: 'md',
  boxShadow: 'md',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}}>
<Typography level="body-sm">MD Shadow</Typography>
</Box>

<Box sx={{
  width: 120,
  height: 80,
  bgcolor: 'background.body',
  borderRadius: 'md',
  boxShadow: 'lg',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}}>
<Typography level="body-sm">LG Shadow</Typography>
</Box>

<Box sx={{
  width: 120,
  height: 80,
  bgcolor: 'background.body',
  borderRadius: 'md',
  boxShadow: 'xl',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}}>
<Typography level="body-sm">XL Shadow</Typography>
</Box>
</div>
```

### Flex Layouts

Flexbox를 사용한 레이아웃을 쉽게 만들 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  flexDirection: 'column',
  gap: '2rem'
}}>
<div>
  <Typography level="title-md" sx={{
    mb: 1
  }}>
  Flex Row (수평 배치)
</Typography>
<Box sx={{
  display: 'flex',
  gap: 1,
  p: 2,
  bgcolor: 'neutral.50',
  borderRadius: 'md'
}}>
<Box sx={{
  p: 2,
  bgcolor: 'primary.100',
  borderRadius: 'sm',
  flex: 1
}}>
<Typography level="body-sm">Item 1</Typography>
</Box>
<Box sx={{
  p: 2,
  bgcolor: 'primary.100',
  borderRadius: 'sm',
  flex: 1
}}>
<Typography level="body-sm">Item 2</Typography>
</Box>
<Box sx={{
  p: 2,
  bgcolor: 'primary.100',
  borderRadius: 'sm',
  flex: 1
}}>
<Typography level="body-sm">Item 3</Typography>
</Box>
</Box>
</div>

<div>
  <Typography level="title-md" sx={{
    mb: 1
  }}>
  Flex Column (수직 배치)
</Typography>
<Box sx={{
  display: 'flex',
  flexDirection: 'column',
  gap: 1,
  p: 2,
  bgcolor: 'neutral.50',
  borderRadius: 'md',
  width: 200
}}>
<Box sx={{
  p: 2,
  bgcolor: 'success.100',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">Item 1</Typography>
</Box>
<Box sx={{
  p: 2,
  bgcolor: 'success.100',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">Item 2</Typography>
</Box>
<Box sx={{
  p: 2,
  bgcolor: 'success.100',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">Item 3</Typography>
</Box>
</Box>
</div>

<div>
  <Typography level="title-md" sx={{
    mb: 1
  }}>
  Center Alignment
</Typography>
<Box sx={{
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center',
  height: 150,
  bgcolor: 'warning.50',
  borderRadius: 'md'
}}>
<Typography level="title-lg">중앙 정렬된 콘텐츠</Typography>
</Box>
</div>
</div>
```

### Responsive Layout

반응형 레이아웃을 구현할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  flexDirection: 'column',
  gap: '2rem'
}}>
<Typography level="title-md">반응형 레이아웃 (브라우저 크기를 조절해보세요)</Typography>

<Box sx={{
  display: 'grid',
  gridTemplateColumns: {
    xs: '1fr',
    sm: 'repeat(2, 1fr)',
    md: 'repeat(3, 1fr)'
  },
  gap: 2,
  p: 2,
  bgcolor: 'neutral.50',
  borderRadius: 'md'
}}>
{[1, 2, 3, 4, 5, 6].map(item => <Box key={item} sx={{
  p: 2,
  bgcolor: 'primary.100',
  borderRadius: 'sm',
  textAlign: 'center'
}}>
<Typography level="body-md">Item {item}</Typography>
</Box>)}
</Box>

<Box sx={{
  p: {
    xs: 2,
    md: 4
  },
  fontSize: {
    xs: 'sm',
    md: 'lg'
  },
  bgcolor: 'success.50',
  borderRadius: 'md',
  textAlign: 'center'
}}>
<Typography>패딩과 폰트 크기가 화면 크기에 따라 달라집니다</Typography>
</Box>
</div>
```

### Polymorphic Components

component prop을 사용하여 다양한 HTML 요소로 렌더링할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  flexDirection: 'column',
  gap: '2rem'
}}>
<Box component="div" sx={{
  p: 2,
  bgcolor: 'neutral.100',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">component="div" (기본값)</Typography>
</Box>

<Box component="section" sx={{
  p: 2,
  bgcolor: 'primary.100',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">component="section"</Typography>
</Box>

<Box component="article" sx={{
  p: 2,
  bgcolor: 'success.100',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">component="article"</Typography>
</Box>

<Box component="nav" sx={{
  p: 2,
  bgcolor: 'warning.100',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">component="nav"</Typography>
</Box>

<Box component="main" sx={{
  p: 2,
  bgcolor: 'danger.100',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">component="main"</Typography>
</Box>
</div>
```

### Motion Animations

내장된 Framer Motion을 사용한 애니메이션 효과입니다.

```tsx
<div style={{
  display: 'flex',
  flexDirection: 'column',
  gap: '2rem',
  alignItems: 'center'
}}>
<button onClick={() => setIsVisible(!isVisible)}>{isVisible ? '숨기기' : '보이기'}</button>

{isVisible && <Box sx={{
  width: 200,
  height: 200,
  bgcolor: 'primary.100',
  borderRadius: 'md',
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
}} initial={{
  opacity: 0,
  scale: 0.8
}} animate={{
  opacity: 1,
  scale: 1
}} exit={{
  opacity: 0,
  scale: 0.8
}} transition={{
  duration: 0.3
}}>
<Typography level="title-md">애니메이션 Box</Typography>
</Box>}

<Box sx={{
  width: 100,
  height: 100,
  bgcolor: 'success.200',
  borderRadius: 'sm',
  cursor: 'pointer'
}} whileHover={{
  scale: 1.1,
  rotate: 5
}} whileTap={{
  scale: 0.95
}} />
<Typography level="body-sm">위의 박스에 마우스를 올려보거나 클릭해보세요</Typography>
</div>
```

### Complex Layouts

Box를 조합하여 복잡한 레이아웃을 만들 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  flexDirection: 'column',
  gap: '2rem'
}}>
<Typography level="title-lg">복잡한 레이아웃 예제</Typography>

{/* Header */}
<Box sx={{
  display: 'flex',
  justifyContent: 'space-between',
  alignItems: 'center',
  p: 3,
  bgcolor: 'primary.50',
  borderRadius: 'lg'
}}>
<Typography level="title-lg">헤더</Typography>
<Box sx={{
  display: 'flex',
  gap: 1
}}>
<Box sx={{
  px: 2,
  py: 1,
  bgcolor: 'primary.200',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">메뉴 1</Typography>
</Box>
<Box sx={{
  px: 2,
  py: 1,
  bgcolor: 'primary.200',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">메뉴 2</Typography>
</Box>
</Box>
</Box>

{/* Main content area */}
<Box sx={{
  display: 'flex',
  gap: 3,
  minHeight: 300
}}>
{/* Sidebar */}
<Box sx={{
  flex: '0 0 200px',
  p: 2,
  bgcolor: 'neutral.50',
  borderRadius: 'md',
  display: 'flex',
  flexDirection: 'column',
  gap: 1
}}>
<Typography level="title-sm" sx={{
  mb: 1
}}>
사이드바
</Typography>
{['Item 1', 'Item 2', 'Item 3'].map(item => <Box key={item} sx={{
  p: 1.5,
  bgcolor: 'background.body',
  borderRadius: 'sm'
}}>
<Typography level="body-sm">{item}</Typography>
</Box>)}
</Box>

{/* Content */}
<Box sx={{
  flex: 1,
  display: 'flex',
  flexDirection: 'column',
  gap: 2
}}>
<Box sx={{
  p: 3,
  bgcolor: 'success.50',
  borderRadius: 'md'
}}>
<Typography level="title-md" sx={{
  mb: 1
}}>
메인 콘텐츠
</Typography>
<Typography level="body-md">
  여기에 주요 콘텐츠가 들어갑니다. Box 컴포넌트를 사용하여 복잡한 레이아웃을 쉽게 만들 수 있습니다.
</Typography>
</Box>

<Box sx={{
  display: 'flex',
  gap: 2
}}>
<Box sx={{
  flex: 1,
  p: 2,
  bgcolor: 'warning.50',
  borderRadius: 'md'
}}>
<Typography level="body-sm">카드 1</Typography>
</Box>
<Box sx={{
  flex: 1,
  p: 2,
  bgcolor: 'warning.50',
  borderRadius: 'md'
}}>
<Typography level="body-sm">카드 2</Typography>
</Box>
</Box>
</Box>
</Box>

{/* Footer */}
<Box sx={{
  p: 2,
  textAlign: 'center',
  bgcolor: 'neutral.100',
  borderRadius: 'md'
}}>
<Typography level="body-sm">푸터 영역</Typography>
</Box>
</div>
```

## Key Features

### SX Prop

Box의 가장 강력한 기능은 `sx` prop입니다. 이를 통해 CSS 스타일을 객체 형태로 직접 적용할 수 있습니다.

```tsx
<Box
  sx={{
    p: 2,                    // padding: 16px
    m: { xs: 1, md: 2 },     // 반응형 마진
    bgcolor: 'primary.50',   // 테마 색상
    borderRadius: 'md',      // 테마 border-radius
    '&:hover': {            // hover 상태
      bgcolor: 'primary.100',
    },
  }}
>
  콘텐츠
</Box>
```

### Responsive Design

객체 구문을 사용해 브레이크포인트별 스타일을 지정할 수 있습니다.

```tsx
<Box
  sx={{
    width: { xs: '100%', md: '50%' },
    p: { xs: 2, md: 4 },
    display: { xs: 'block', md: 'flex' },
  }}
>
  반응형 박스
</Box>
```

### Theme Integration

디자인 시스템의 토큰을 직접 사용할 수 있습니다.

```tsx
<Box
  sx={{
    bgcolor: 'background.level1',
    color: 'text.primary',
    borderRadius: 'sm',
    boxShadow: 'md',
  }}
>
  테마 통합 박스
</Box>
```

### Framer Motion

애니메이션 props를 직접 사용할 수 있습니다.

```tsx
<Box
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.3 }}
  whileHover={{ scale: 1.05 }}
>
  애니메이션 박스
</Box>
```

## Common Use Cases

### Layout Container

```tsx
<Box sx={{ maxWidth: 1200, mx: 'auto', p: 3 }}>
  <Typography level="h1">페이지 제목</Typography>
  {/* 페이지 콘텐츠 */}
</Box>
```

### Card-like Components

```tsx
<Box
  sx={{
    p: 3,
    bgcolor: 'background.body',
    borderRadius: 'lg',
    boxShadow: 'sm',
    border: '1px solid',
    borderColor: 'divider',
  }}
>
  <Typography level="title-md">카드 제목</Typography>
  <Typography level="body-md">카드 내용</Typography>
</Box>
```

### Flexbox Layouts

```tsx
<Box sx={{ display: 'flex', gap: 2, alignItems: 'center' }}>
  <Avatar />
  <Box sx={{ flex: 1 }}>
    <Typography level="title-sm">사용자 이름</Typography>
    <Typography level="body-xs">부가 정보</Typography>
  </Box>
</Box>
```

### Grid Layouts

```tsx
<Box
  sx={{
    display: 'grid',
    gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))',
    gap: 2,
  }}
>
  {items.map(item => (
    <Box key={item.id} sx={{ p: 2, bgcolor: 'background.surface' }}>
      {item.content}
    </Box>
  ))}
</Box>
```

### Centered Content

```tsx
<Box
  sx={{
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
    minHeight: '100vh',
  }}
>
  <Typography level="h1">중앙 정렬된 콘텐츠</Typography>
</Box>
```

### Sticky/Fixed Positioning

```tsx
<Box
  sx={{
    position: 'sticky',
    top: 0,
    zIndex: 1000,
    bgcolor: 'background.body',
    borderBottom: '1px solid',
    borderColor: 'divider',
  }}
>
  <Typography>고정된 헤더</Typography>
</Box>
```

## Best Practices

1. **의미 있는 HTML 요소 사용**: `component` prop을 활용해 의미론적으로 올바른 HTML 요소를 선택하세요.

2. **테마 토큰 활용**: 하드코딩된 값 대신 테마의 spacing, color, border-radius 등을 사용하세요.

3. **반응형 고려**: 다양한 화면 크기에서 잘 동작하도록 반응형 값을 사용하세요.

4. **성능 최적화**:
   - 인라인 객체 생성을 피하고 가능하면 객체를 메모화하세요
   - 복잡한 애니메이션은 필요할 때만 사용하세요

5. **접근성**:
   - 적절한 semantic HTML 요소를 선택하세요
   - 필요시 ARIA 속성을 추가하세요
   - 충분한 색상 대비를 유지하세요

6. **재사용성**:
   - 자주 사용하는 스타일 조합은 별도 컴포넌트로 분리하세요
   - 공통 스타일은 테마에 정의하세요

7. **일관성**:
   - 팀 내에서 일관된 spacing과 naming convention을 사용하세요
   - 디자인 시스템의 가이드라인을 따르세요

## Spacing Scale

Box에서 사용할 수 있는 spacing 값들:

- `0.5` = 4px
- `1` = 8px
- `1.5` = 12px
- `2` = 16px
- `3` = 24px
- `4` = 32px
- `5` = 40px
- `6` = 48px

## Color Tokens

주요 색상 토큰들:

- **Background**: `background.body`, `background.surface`, `background.level1`
- **Primary**: `primary.50`, `primary.100`, `primary.500`, `primary.main`
- **Neutral**: `neutral.50`, `neutral.100`, `neutral.500`, `neutral.main`
- **Text**: `text.primary`, `text.secondary`, `text.tertiary`

Box는 ADS의 모든 레이아웃과 스타일링의 기초가 되는 컴포넌트입니다. 강력한 sx prop과 내장된 애니메이션 기능을 활용해 다양한 UI 요구사항을 충족할 수 있습니다.
