세부타입설정

2025-10-14 16:45:30 +09:00
parent 8bc8df4eb8
commit a2c3737f7a
25 changed files with 1724 additions and 306 deletions
--- a/docs/그리드_컬럼수_옵션_통합.md
+++ b/docs/그리드_컬럼수_옵션_통합.md
@@ -0,0 +1,223 @@
+# 그리드 컬럼 수 옵션 통합
+
+## 개요
+
+"그리드 컬럼 수" 옵션과 "컴포넌트 너비" 옵션이 중복된 기능을 제공하여 혼란을 야기했습니다.
+사용자 편의성을 위해 **"컴포넌트 너비" 옵션만 사용**하도록 통합하고, 내부적으로 `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` 자동 계산 로직 추가
--- a/docs/컴포넌트_기본_너비_설정_가이드.md
+++ b/docs/컴포넌트_기본_너비_설정_가이드.md
@@ -0,0 +1,225 @@
+# 컴포넌트 기본 너비 설정 가이드
+
+## 개요
+
+화면 관리에서 각 컴포넌트 타입별로 적절한 기본 너비를 설정하고, 컴포넌트가 지정된 너비를 벗어나지 않도록 스타일을 적용했습니다.
+
+## 변경 사항
+
+### 1. 인풋 컴포넌트 기본 너비 조정
+
+각 인풋 타입별로 적절한 기본 크기를 설정했습니다:
+
+#### 텍스트 입력 계열
+
+- **텍스트 입력** (`text-input`): 300px × 40px
+- **숫자 입력** (`number-input`): 200px × 40px
+- **텍스트 영역** (`textarea-basic`): 400px × 100px
+
+#### 선택 입력 계열
+
+- **선택상자** (`select-basic`): 250px × 40px
+- **날짜 선택** (`date-input`): 220px × 40px
+- **체크박스** (`checkbox-basic`): 150px × 32px
+- **라디오 버튼** (`radio-basic`): 150px × 32px
+- **슬라이더** (`slider-basic`): 250px × 40px
+- **토글 스위치** (`toggle-switch`): 180px × 40px
+
+#### 파일 및 기타
+
+- **파일 업로드** (`file-upload`): 350px × 40px
+
+#### 표시 컴포넌트
+
+- **기본 버튼** (`button-primary`): 120px × 40px
+- **텍스트 표시** (`text-display`): 150px × 24px
+- **이미지 표시** (`image-display`): 200px × 200px
+- **구분선** (`divider-line`): 400px × 2px
+- **아코디언** (`accordion-basic`): 400px × 200px
+
+#### 데이터 컴포넌트
+
+- **테이블 리스트** (`table-list`): 120px × 600px
+- **카드 표시** (`card-display`): 기존 유지
+
+### 2. 공통 스타일 적용
+
+`/frontend/lib/registry/components/common/inputStyles.ts` 파일의 모든 스타일 클래스에 다음을 추가:
+
+- `max-w-full`: 최대 너비를 부모 컨테이너로 제한
+- `overflow-hidden`: 내용이 넘칠 경우 숨김 처리
+
+적용된 클래스:
+
+- `INPUT_CLASSES.base`
+- `INPUT_CLASSES.container`
+- `INPUT_CLASSES.textarea`
+- `INPUT_CLASSES.select`
+- `INPUT_CLASSES.flexContainer`
+
+### 3. 개별 컴포넌트 스타일 적용
+
+#### TextInputComponent
+
+- 컨테이너 div: `max-w-full overflow-hidden` 추가
+- input 요소: `max-w-full` 추가
+- textarea 요소: `max-w-full` 추가
+
+#### RealtimePreviewDynamic
+
+- 컴포넌트 렌더링 컨테이너: `max-w-full overflow-hidden` 추가
+
+## 적용 효과
+
+### 1. 일관된 초기 크기
+
+- 컴포넌트 드래그 앤 드롭 시 각 타입별로 적절한 기본 크기로 생성됨
+- 사용자가 별도로 크기를 조정할 필요 없이 바로 사용 가능
+
+### 2. 그리드 시스템과의 통합
+
+- **그리드 활성화 시**: `defaultSize.width`를 기준으로 적절한 그리드 컬럼 수 자동 계산
+  - 예: 300px 너비 → 약 3-4 컬럼 (그리드 설정에 따라 다름)
+  - 계산된 컬럼 수에 맞춰 정확한 너비로 재조정
+- **그리드 비활성화 시**: `defaultSize`의 픽셀 값을 그대로 사용
+- 일관된 사용자 경험 제공
+
+### 3. 너비 제한
+
+- 컴포넌트가 설정된 너비를 벗어나지 않음
+- 부모 컨테이너 크기에 맞춰 자동으로 조정됨
+- 레이아웃 깨짐 방지
+
+### 4. 반응형 대응
+
+- `max-w-full` 속성으로 부모 컨테이너에 맞춰 자동 축소
+- `overflow-hidden`으로 내용 넘침 방지
+
+## 사용 방법
+
+### 새 컴포넌트 생성 시
+
+1. 컴포넌트 팔레트에서 원하는 타입 선택
+2. 캔버스에 드래그 앤 드롭
+3. 자동으로 적절한 기본 크기로 생성됨
+
+### 크기 조정
+
+1. 컴포넌트 선택
+2. 속성 패널에서 "컴포넌트 너비" 선택
+3. 드롭다운에서 원하는 너비 선택 (1/12 ~ 12/12)
+4. 또는 직접 픽셀 값 입력
+
+## 주의 사항
+
+### 기존 화면에 미치는 영향
+
+- 이미 생성된 컴포넌트는 영향 받지 않음
+- 새로 생성되는 컴포넌트만 새로운 기본값 적용
+
+### 스타일 우선순위
+
+1. 인라인 style 속성
+2. componentConfig에서 설정한 크기
+3. defaultSize (새로 적용된 기본값)
+
+### 커스터마이징
+
+- 각 컴포넌트의 `index.ts` 파일에서 `defaultSize` 수정 가능
+- 프로젝트 요구사항에 맞춰 조정 가능
+
+## 테스트 방법
+
+### 기본 크기 테스트
+
+```
+1. 화면 디자이너 열기
+2. 각 인풋 타입 컴포넌트를 캔버스에 드롭
+3. 기본 크기가 적절한지 확인
+4. 여러 컴포넌트를 나란히 배치하여 일관성 확인
+```
+
+### 너비 제한 테스트
+
+```
+1. 컴포넌트 생성 후 선택
+2. 속성 패널에서 너비를 작은 값으로 설정 (예: 100px)
+3. 컴포넌트 내부의 input이 너비를 벗어나지 않는지 확인
+4. 긴 텍스트 입력 시 overflow 처리 확인
+```
+
+### 반응형 테스트
+
+```
+1. 레이아웃 컨테이너 내부에 컴포넌트 배치
+2. 레이아웃 크기를 조정하여 컴포넌트가 적절히 축소되는지 확인
+3. 다양한 화면 해상도에서 테스트
+```
+
+## 관련 파일
+
+### 컴포넌트 정의 파일
+
+- `/frontend/lib/registry/components/text-input/index.ts`
+- `/frontend/lib/registry/components/number-input/index.ts`
+- `/frontend/lib/registry/components/select-basic/index.ts`
+- `/frontend/lib/registry/components/date-input/index.ts`
+- `/frontend/lib/registry/components/textarea-basic/index.ts`
+- `/frontend/lib/registry/components/checkbox-basic/index.ts`
+- `/frontend/lib/registry/components/radio-basic/index.ts`
+- `/frontend/lib/registry/components/file-upload/index.ts`
+- `/frontend/lib/registry/components/slider-basic/index.ts`
+- `/frontend/lib/registry/components/toggle-switch/index.ts`
+- `/frontend/lib/registry/components/button-primary/index.ts`
+- `/frontend/lib/registry/components/text-display/index.ts`
+- `/frontend/lib/registry/components/image-display/index.ts`
+- `/frontend/lib/registry/components/divider-line/index.ts`
+- `/frontend/lib/registry/components/accordion-basic/index.ts`
+- `/frontend/lib/registry/components/table-list/index.ts`
+
+### 공통 스타일 파일
+
+- `/frontend/lib/registry/components/common/inputStyles.ts`
+
+### 렌더링 관련 파일
+
+- `/frontend/components/screen/RealtimePreviewDynamic.tsx`
+- `/frontend/lib/registry/components/text-input/TextInputComponent.tsx`
+
+### 화면 디자이너
+
+- `/frontend/components/screen/ScreenDesigner.tsx`
+  - `handleComponentDrop` 함수 (1751-1800줄): 컴포넌트 드롭 시 그리드 컬럼 수 자동 계산
+  - 그리드 활성화 시: `defaultSize.width` 기반으로 gridColumns 계산 후 너비 재조정
+  - 그리드 비활성화 시: `defaultSize` 그대로 사용
+
+## 향후 개선 사항
+
+### 1. 반응형 기본값
+
+- 화면 크기에 따라 다른 기본값 적용
+- 모바일, 태블릿, 데스크톱 각각 최적화
+
+### 2. 사용자 정의 기본값
+
+- 사용자가 자주 사용하는 크기를 기본값으로 저장
+- 프로젝트별 기본값 설정 기능
+
+### 3. 스마트 크기 조정
+
+- 주변 컴포넌트에 맞춰 자동으로 크기 조정
+- 레이블 길이에 따른 동적 너비 계산
+
+### 4. 프리셋 제공
+
+- 폼 레이아웃 프리셋 (라벨-입력 쌍)
+- 검색 바 프리셋
+- 로그인 폼 프리셋
+
+## 버전 히스토리
+
+### v1.0.0 (2025-10-14)
+
+- 초기 기본 너비 설정 적용
+- 공통 스타일에 max-w-full, overflow-hidden 추가
+- 모든 인풋 컴포넌트 기본 크기 조정
--- a/docs/테이블_패널_컴포넌트_기본_너비_설정.md
+++ b/docs/테이블_패널_컴포넌트_기본_너비_설정.md
@@ -0,0 +1,322 @@
+# 테이블 패널 컴포넌트 기본 너비 설정
+
+## 개요
+
+테이블 패널에서 컬럼과 필터를 드래그 드롭으로 추가할 때, 각 웹타입별로 적절한 기본 너비(gridColumns)가 자동으로 설정되도록 개선했습니다.
+
+## 문제점
+
+### 기존 방식
+
+- **모든 컬럼**: `gridColumns: 2` (2/12, 16.67%) 고정
+- **모든 필터**: `gridColumns: 3` (3/12, 25%) 고정
+- 웹타입에 관계없이 동일한 너비 적용
+- 긴 텍스트 입력이나 짧은 숫자 입력 모두 같은 크기
+
+### 문제 사례
+
+```
+❌ text (긴 텍스트) → 2컬럼 (너무 좁음)
+❌ textarea (여러 줄) → 2컬럼 (너무 좁음)
+❌ checkbox (체크박스) → 2컬럼 (너무 넓음)
+```
+
+## 해결 방법
+
+### 웹타입별 기본 너비 함수 추가
+
+```typescript
+// DataTableConfigPanel.tsx (891-929줄)
+const getDefaultGridColumns = (webType: WebType): number => {
+  const widthMap: Record<WebType, number> = {
+    // 텍스트 입력 계열 (넓게)
+    text: 4, // 1/3 (33%)
+    email: 4, // 1/3 (33%)
+    tel: 3, // 1/4 (25%)
+    url: 4, // 1/3 (33%)
+    textarea: 6, // 절반 (50%)
+
+    // 숫자/날짜 입력 (중간)
+    number: 2, // 2/12 (16.67%)
+    decimal: 2, // 2/12 (16.67%)
+    date: 3, // 1/4 (25%)
+    datetime: 3, // 1/4 (25%)
+    time: 2, // 2/12 (16.67%)
+
+    // 선택 입력 (중간)
+    select: 3, // 1/4 (25%)
+    radio: 3, // 1/4 (25%)
+    checkbox: 2, // 2/12 (16.67%)
+    boolean: 2, // 2/12 (16.67%)
+
+    // 코드/참조 (넓게)
+    code: 3, // 1/4 (25%)
+    entity: 4, // 1/3 (33%)
+
+    // 파일/이미지 (넓게)
+    file: 4, // 1/3 (33%)
+    image: 3, // 1/4 (25%)
+
+    // 기타
+    button: 2, // 2/12 (16.67%)
+    label: 2, // 2/12 (16.67%)
+  };
+
+  return widthMap[webType] || 3; // 기본값 3 (1/4, 25%)
+};
+```
+
+## 적용된 함수
+
+### 1. addColumn (컬럼 추가)
+
+```typescript
+// Before
+const newColumn: DataTableColumn = {
+  // ...
+  gridColumns: 2, // ❌ 모든 타입에 2 고정
+  // ...
+};
+
+// After
+const newColumn: DataTableColumn = {
+  // ...
+  gridColumns: getDefaultGridColumns(widgetType), // ✅ 웹타입별 자동 계산
+  // ...
+};
+```
+
+### 2. addFilter (필터 추가)
+
+```typescript
+// Before
+const newFilter: DataTableFilter = {
+  // ...
+  gridColumns: 3, // ❌ 모든 타입에 3 고정
+  // ...
+};
+
+// After
+const newFilter: DataTableFilter = {
+  // ...
+  gridColumns: getDefaultGridColumns(widgetType), // ✅ 웹타입별 자동 계산
+  // ...
+};
+```
+
+### 3. addVirtualFileColumn (가상 파일 컬럼 추가)
+
+```typescript
+// Before
+const newColumn: DataTableColumn = {
+  // ...
+  widgetType: "file",
+  gridColumns: 2, // ❌ 파일 타입에 2 고정
+  // ...
+};
+
+// After
+const newColumn: DataTableColumn = {
+  // ...
+  widgetType: "file",
+  gridColumns: getDefaultGridColumns("file"), // ✅ 파일 타입 기본값 (4컬럼, 33%)
+  // ...
+};
+```
+
+## 웹타입별 기본 너비 상세
+
+### 텍스트 입력 계열 (넓게 설정)
+
+| 웹타입   | 컬럼 수 | 퍼센트 | 설명                       |
+| -------- | ------- | ------ | -------------------------- |
+| text     | 4       | 33%    | 일반 텍스트 입력           |
+| email    | 4       | 33%    | 이메일 주소 (길이 필요)    |
+| tel      | 3       | 25%    | 전화번호 (중간 길이)       |
+| url      | 4       | 33%    | URL 주소 (길이 필요)       |
+| textarea | 6       | 50%    | 여러 줄 텍스트 (가장 넓게) |
+
+### 숫자/날짜 입력 (중간 설정)
+
+| 웹타입   | 컬럼 수 | 퍼센트 | 설명           |
+| -------- | ------- | ------ | -------------- |
+| number   | 2       | 16.67% | 정수 입력      |
+| decimal  | 2       | 16.67% | 소수 입력      |
+| date     | 3       | 25%    | 날짜 선택      |
+| datetime | 3       | 25%    | 날짜+시간 선택 |
+| time     | 2       | 16.67% | 시간 선택      |
+
+### 선택 입력 (중간 설정)
+
+| 웹타입   | 컬럼 수 | 퍼센트 | 설명            |
+| -------- | ------- | ------ | --------------- |
+| select   | 3       | 25%    | 드롭다운 선택   |
+| radio    | 3       | 25%    | 라디오 버튼     |
+| checkbox | 2       | 16.67% | 체크박스 (작게) |
+| boolean  | 2       | 16.67% | 참/거짓 (작게)  |
+
+### 코드/참조 (넓게 설정)
+
+| 웹타입 | 컬럼 수 | 퍼센트 | 설명                    |
+| ------ | ------- | ------ | ----------------------- |
+| code   | 3       | 25%    | 코드 선택               |
+| entity | 4       | 33%    | 엔티티 참조 (길이 필요) |
+
+### 파일/이미지 (넓게 설정)
+
+| 웹타입 | 컬럼 수 | 퍼센트 | 설명          |
+| ------ | ------- | ------ | ------------- |
+| file   | 4       | 33%    | 파일 업로드   |
+| image  | 3       | 25%    | 이미지 업로드 |
+
+### 기타
+
+| 웹타입     | 컬럼 수 | 퍼센트 | 설명               |
+| ---------- | ------- | ------ | ------------------ |
+| button     | 2       | 16.67% | 버튼               |
+| label      | 2       | 16.67% | 라벨               |
+| **기본값** | 3       | 25%    | 정의되지 않은 타입 |
+
+## 적용 효과
+
+### Before (기존)
+
+```
+[컬럼 추가]
+- 이름 (text) → 2컬럼 → 너무 좁음 😞
+- 설명 (textarea) → 2컬럼 → 너무 좁음 😞
+- 나이 (number) → 2컬럼 → 적절함 😐
+- 활성화 (checkbox) → 2컬럼 → 너무 넓음 😞
+
+[필터 추가]
+- 검색어 (text) → 3컬럼 → 약간 좁음 😐
+- 날짜 (date) → 3컬럼 → 적절함 😐
+- 승인 (boolean) → 3컬럼 → 너무 넓음 😞
+```
+
+### After (개선)
+
+```
+[컬럼 추가]
+- 이름 (text) → 4컬럼 (33%) → 적절함 ✅
+- 설명 (textarea) → 6컬럼 (50%) → 충분함 ✅
+- 나이 (number) → 2컬럼 (16.67%) → 적절함 ✅
+- 활성화 (checkbox) → 2컬럼 (16.67%) → 적절함 ✅
+
+[필터 추가]
+- 검색어 (text) → 4컬럼 (33%) → 충분함 ✅
+- 날짜 (date) → 3컬럼 (25%) → 적절함 ✅
+- 승인 (boolean) → 2컬럼 (16.67%) → 적절함 ✅
+```
+
+## 사용 방법
+
+### 1. 컬럼 추가
+
+1. 테이블 선택
+2. "컬럼 추가" 버튼 클릭 또는 드롭다운에서 컬럼 선택
+3. 웹타입에 맞는 기본 너비로 자동 생성됨
+4. 필요시 속성 패널에서 너비 조정 가능
+
+### 2. 필터 추가
+
+1. 테이블 선택
+2. "필터 추가" 버튼 클릭
+3. 웹타입에 맞는 기본 너비로 자동 생성됨
+4. 필요시 컬럼별 너비 조정 가능
+
+### 3. 가상 파일 컬럼 추가
+
+1. "파일 컬럼" 버튼 클릭
+2. 파일 타입에 맞는 기본 너비(4컬럼, 33%)로 생성됨
+
+### 4. 너비 조정 (수동)
+
+**컬럼 너비 조정**:
+
+- 컬럼 설정 탭에서 각 컬럼별 "컬럼 너비" 드롭다운 선택
+- 1/12 (8.33%)부터 12/12 (100%)까지 선택 가능
+- 기본값은 웹타입에 따라 자동 설정됨
+
+**필터 너비 조정**:
+
+- 필터 설정 탭에서 각 필터별 "필터 너비" 드롭다운 선택
+- 1/12 (8.33%)부터 12/12 (100%)까지 선택 가능
+- 기본값은 웹타입에 따라 자동 설정됨
+
+## 주의 사항
+
+### 기존 데이터
+
+- **영향 없음**: 이미 생성된 컬럼/필터는 변경되지 않음
+- **새로 추가되는 항목만** 새로운 기본값 적용
+
+### 커스터마이징
+
+- 기본값이 맞지 않으면 수동으로 조정 가능
+- 자주 사용하는 너비가 있다면 `getDefaultGridColumns` 함수 수정 가능
+
+### 레이아웃 고려
+
+- 한 행에 총 12컬럼까지 배치 가능
+- 예: 4컬럼 + 4컬럼 + 4컬럼 = 12컬럼 (딱 맞음)
+- 예: 4컬럼 + 4컬럼 + 6컬럼 = 14컬럼 (넘침 → 다음 줄로 이동)
+
+## 테스트 체크리스트
+
+### 컬럼 추가 테스트
+
+- [ ] text 타입 컬럼 추가 → 4컬럼(33%) 확인
+- [ ] number 타입 컬럼 추가 → 2컬럼(16.67%) 확인
+- [ ] textarea 타입 컬럼 추가 → 6컬럼(50%) 확인
+- [ ] select 타입 컬럼 추가 → 3컬럼(25%) 확인
+- [ ] checkbox 타입 컬럼 추가 → 2컬럼(16.67%) 확인
+
+### 필터 추가 테스트
+
+- [ ] text 타입 필터 추가 → 4컬럼(33%) 확인
+- [ ] date 타입 필터 추가 → 3컬럼(25%) 확인
+- [ ] boolean 타입 필터 추가 → 2컬럼(16.67%) 확인
+
+### 가상 파일 컬럼 테스트
+
+- [ ] 파일 컬럼 추가 → 4컬럼(33%) 확인
+
+### 수동 조정 테스트
+
+- [ ] 생성 후 너비 수동 변경 가능한지 확인
+- [ ] 변경된 너비가 저장/로드 시 유지되는지 확인
+
+## 관련 파일
+
+### 수정된 파일
+
+#### 1. `/frontend/components/screen/panels/DataTableConfigPanel.tsx`
+
+- `getDefaultGridColumns` 함수 추가 (891-929줄)
+- `addColumn` 함수 수정 (954줄) - 웹타입별 기본 너비 자동 계산
+- `addFilter` 함수 수정 (781줄) - 웹타입별 기본 너비 자동 계산
+- `addVirtualFileColumn` 함수 수정 (1055줄) - 파일 타입 기본 너비 적용
+- 컬럼 설정 UI 개선 (1652줄) - "그리드 컬럼" → "컬럼 너비" (1/12 ~ 12/12)
+- 필터 설정 UI 개선 (2131줄) - "그리드 컬럼" → "필터 너비" (1/12 ~ 12/12)
+
+#### 2. `/frontend/components/screen/ScreenDesigner.tsx`
+
+- `getDefaultGridColumns` 함수 추가 (1946-1984줄) - 드래그 드롭 컴포넌트용
+- `getDefaultGridColumnsForTemplate` 함수 추가 (1429-1438줄) - 템플릿 컴포넌트용
+- 템플릿 컴포넌트 생성 시 기본 너비 적용 (1514줄)
+- 폼 컨테이너 내 컴포넌트 생성 시 기본 너비 적용 (2151줄)
+- 드래그 드롭 컴포넌트 생성 시 기본 너비 적용 (2194줄)
+
+### 관련 문서
+
+- [컴포넌트*기본*너비*설정*가이드.md](./컴포넌트_기본_너비_설정_가이드.md)
+- [그리드*컬럼수*옵션\_통합.md](./그리드_컬럼수_옵션_통합.md)
+
+## 버전 히스토리
+
+### v1.0.0 (2025-10-14)
+
+- 웹타입별 기본 너비 자동 설정 기능 추가
+- `getDefaultGridColumns` 함수 구현
+- `addColumn`, `addFilter`, `addVirtualFileColumn` 함수에 적용