ERP-node/docs/그리드_컬럼수_옵션_통합.md

그리드 컬럼 수 옵션 통합

개요

"그리드 컬럼 수" 옵션과 "컴포넌트 너비" 옵션이 중복된 기능을 제공하여 혼란을 야기했습니다. 사용자 편의성을 위해 "컴포넌트 너비" 옵션만 사용하도록 통합하고, 내부적으로 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 자동 계산:

// 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. 컴포넌트 생성 시 동작

// 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

버전 히스토리

v1.0.0 (2025-10-14)

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