# 그리드 컬럼 수 옵션 통합

## 개요

"그리드 컬럼 수" 옵션과 "컴포넌트 너비" 옵션이 중복된 기능을 제공하여 혼란을 야기했습니다.
사용자 편의성을 위해 **"컴포넌트 너비" 옵션만 사용**하도록 통합하고, 내부적으로 `gridColumns` 값을 자동 계산하도록 변경했습니다.

## 문제점

### 기존 상황

1. **그리드 컬럼 수 옵션**: 1-12 숫자 입력
2. **컴포넌트 너비 옵션**: 1/12 ~ 12/12 선택 (퍼센트로 변환)

→ 같은 기능을 두 가지 방식으로 제공하여 사용자 혼란 발생

### 예시

- 사용자가 "그리드 컬럼 수"를 6으로 설정
- 하지만 "컴포넌트 너비"가 1/4 (3컬럼)로 설정되어 있음
- 두 설정이 충돌하여 예상과 다른 결과 발생

## 해결 방법

### 1. UI 단순화

**제거된 옵션**:

- ❌ PropertiesPanel의 "그리드 컬럼 수 (1-12)" 입력 필드
- ❌ DataTableConfigPanel의 "그리드 컬럼 수" 선택 상자

**유지된 옵션**:

- ✅ PropertiesPanel의 "컴포넌트 너비" 선택 상자 (1/12 ~ 12/12)

### 2. 자동 계산 로직

컴포넌트 너비 선택 시 `gridColumns` 자동 계산:

```typescript
// PropertiesPanel.tsx (764-788줄)
const columnsMap: Record<string, number> = {
  twelfth: 1, // 1/12
  small: 2, // 2/12
  quarter: 3, // 3/12 (1/4)
  third: 4, // 4/12 (1/3)
  "five-twelfths": 5, // 5/12
  half: 6, // 6/12 (절반)
  "seven-twelfths": 7, // 7/12
  twoThirds: 8, // 8/12 (2/3)
  threeQuarters: 9, // 9/12 (3/4)
  "five-sixths": 10, // 10/12
  "eleven-twelfths": 11, // 11/12
  full: 12, // 12/12 (전체)
};

// 컴포넌트 너비 변경 시
onUpdateProperty("style.width", newWidth); // 퍼센트 값 저장
const gridColumns = columnsMap[value] || 6;
onUpdateProperty("gridColumns", gridColumns); // 컬럼 수 자동 계산
```

### 3. 컴포넌트 생성 시 동작

```typescript
// ScreenDesigner.tsx (1756-1772줄)
// 일반 컴포넌트: defaultSize.width를 기준으로 그리드 컬럼 수 계산
if (layout.gridSettings?.snapToGrid && gridInfo) {
  const columnWidth = gridInfo.columnWidth + gridInfo.gap;
  const estimatedColumns = Math.round(
    component.defaultSize.width / columnWidth
  );
  gridColumns = Math.max(1, Math.min(12, estimatedColumns)); // 1-12 범위
}
```

## 변경 사항

### 파일 수정

#### 1. PropertiesPanel.tsx

- ❌ 삭제: "그리드 컬럼 수" 입력 필드 (916-940줄)
- ❌ 삭제: `localInputs.gridColumns` 상태 (206-213줄)
- ✅ 추가: 컴포넌트 너비 변경 시 `gridColumns` 자동 계산 (764-788줄)

#### 2. DataTableConfigPanel.tsx

- ❌ 삭제: "그리드 컬럼 수" 선택 상자 (1437-1456줄)
- ❌ 삭제: `localValues.gridColumns` 초기화 (72줄, 182줄)

#### 3. ScreenDesigner.tsx

- ✅ 개선: 컴포넌트 드롭 시 `defaultSize.width` 기반으로 `gridColumns` 자동 계산 (1756-1772줄)

## 사용 방법

### 컴포넌트 너비 조정

#### 방법 1: 드롭다운 선택

1. 컴포넌트 선택
2. 속성 패널 > "컴포넌트 너비" 드롭다운
3. 원하는 너비 선택 (예: "절반 (6/12)")
4. 자동으로 `style.width`와 `gridColumns` 모두 업데이트됨

#### 방법 2: 컴포넌트 생성 시

1. 컴포넌트 팔레트에서 드래그
2. 캔버스에 드롭
3. `defaultSize.width`를 기준으로 적절한 `gridColumns` 자동 설정

### 너비 옵션 설명

| 옵션         | 컬럼 수 | 퍼센트 | 설명        |
| ------------ | ------- | ------ | ----------- |
| 1/12         | 1       | 8.33%  | 최소        |
| 작게 (2/12)  | 2       | 16.67% | 매우 작음   |
| 1/4 (3/12)   | 3       | 25%    | 4등분의 1   |
| 1/3 (4/12)   | 4       | 33.33% | 3등분의 1   |
| 5/12         | 5       | 41.67% |             |
| 절반 (6/12)  | 6       | 50%    | 정확히 절반 |
| 7/12         | 7       | 58.33% |             |
| 2/3 (8/12)   | 8       | 66.67% | 3등분의 2   |
| 3/4 (9/12)   | 9       | 75%    | 4등분의 3   |
| 10/12        | 10      | 83.33% |             |
| 11/12        | 11      | 91.67% |             |
| 전체 (12/12) | 12      | 100%   | 최대        |

## 적용 효과

### 1. 사용자 경험 개선

- ✅ 단일 옵션으로 간소화
- ✅ 직관적인 분수 표현 (1/4, 절반, 2/3 등)
- ✅ 설정 충돌 제거

### 2. 일관성 보장

- ✅ 컴포넌트 너비와 gridColumns 항상 동기화
- ✅ 그리드 시스템과 자연스러운 통합

### 3. 개발자 편의

- ✅ 내부적으로 gridColumns는 여전히 사용 가능
- ✅ 기존 데이터 호환성 유지 (gridColumns 필드 존재)

## 내부 동작

### gridColumns 사용처

`gridColumns` 값은 사용자에게 직접 노출되지 않지만, 내부적으로 여전히 중요한 역할을 합니다:

1. **그리드 레이아웃 계산**: 컴포넌트가 차지할 그리드 셀 수 결정
2. **자동 배치**: 컴포넌트 자동 정렬 시 참조
3. **반응형 조정**: 화면 크기 변경 시 비율 유지

### 값 동기화 흐름

```
사용자 선택: "절반 (6/12)"
    ↓
1. style.width = "50%" 저장
    ↓
2. gridColumns = 6 자동 계산
    ↓
3. 그리드 시스템에서 6컬럼 너비로 렌더링
    ↓
4. 실제 픽셀 너비 계산 및 적용
```

## 마이그레이션 가이드

### 기존 화면 데이터

- **영향 없음**: 기존에 저장된 `gridColumns` 값은 그대로 유지
- **자동 변환**: 컴포넌트 편집 시 `style.width`로부터 재계산

### 사용자 교육

1. "그리드 컬럼 수" 설정이 제거되었음을 안내
2. "컴포넌트 너비"로 동일한 기능 사용 가능
3. 더 직관적인 분수 표현 (1/4, 1/2 등) 강조

## 테스트 체크리스트

### UI 확인

- [ ] PropertiesPanel에 "그리드 컬럼 수" 입력 필드가 없는지 확인
- [ ] DataTableConfigPanel에 "그리드 컬럼 수" 선택 상자가 없는지 확인
- [ ] "컴포넌트 너비" 드롭다운이 정상 작동하는지 확인

### 기능 확인

- [ ] 컴포넌트 너비 변경 시 시각적으로 제대로 반영되는지 확인
- [ ] 새 컴포넌트 생성 시 적절한 초기 너비로 생성되는지 확인
- [ ] 그리드 ON/OFF 시 너비가 올바르게 적용되는지 확인

### 데이터 확인

- [ ] 컴포넌트 너비 변경 후 저장/불러오기 테스트
- [ ] 기존 화면 데이터가 정상적으로 로드되는지 확인
- [ ] `gridColumns` 값이 자동으로 계산되는지 확인

## 관련 파일

### 수정된 파일

- `/frontend/components/screen/panels/PropertiesPanel.tsx`
- `/frontend/components/screen/panels/DataTableConfigPanel.tsx`
- `/frontend/components/screen/ScreenDesigner.tsx`

### 관련 문서

- [컴포넌트*기본*너비*설정*가이드.md](./컴포넌트_기본_너비_설정_가이드.md)

## 버전 히스토리

### v1.0.0 (2025-10-14)

- "그리드 컬럼 수" 옵션 제거
- "컴포넌트 너비" 옵션으로 통합
- `gridColumns` 자동 계산 로직 추가