# POP 컴포넌트 상세 설계서

> AI 에이전트 안내: Quick Reference 먼저 확인 후 필요한 섹션만 참조

---

## Quick Reference

### 총 컴포넌트 수: 15개 (🆕 줄바꿈 추가)

| 분류 | 개수 | 컴포넌트 |
|------|------|----------|
| 레이아웃 | 4 | container, tab-panel, **spacer**, **break 🆕** |
| 데이터 표시 | 4 | data-table, card-list, kpi-gauge, status-indicator |
| 입력 | 4 | number-pad, barcode-scanner, form-field, action-button |
| 특화 기능 | 3 | timer, alarm-list, process-flow |

### 개발 우선순위

1단계: number-pad, status-indicator, kpi-gauge, action-button
2단계: data-table, card-list, barcode-scanner, timer
3단계: container, tab-panel, form-field, alarm-list, process-flow

### POP UI 필수 원칙

- 버튼 최소 크기: 48px (1.5cm)
- 고대비 테마 지원
- 단순 탭 조작 (스와이프 최소화)
- 알람에만 원색 사용
- 숫자 우측 정렬

---

## 컴포넌트 목록

| # | 컴포넌트 | 역할 |
|---|----------|------|
| 1 | pop-container | 레이아웃 뼈대 |
| 2 | pop-tab-panel | 정보 분류 |
| 3 | **pop-spacer** | **빈 공간 (정렬용)** |
| 4 | **pop-break 🆕** | **강제 줄바꿈 (Flexbox)** |
| 5 | pop-data-table | 대량 데이터 |
| 6 | pop-card-list | 시각적 목록 |
| 7 | pop-kpi-gauge | 목표 달성률 |
| 8 | pop-status-indicator | 상태 표시 |
| 9 | pop-number-pad | 수량 입력 |
| 10 | pop-barcode-scanner | 스캔 입력 |
| 11 | pop-form-field | 범용 입력 |
| 12 | pop-action-button | 작업 실행 |
| 13 | pop-timer | 시간 측정 |
| 14 | pop-alarm-list | 알람 관리 |
| 15 | pop-process-flow | 공정 현황 |

---

## 1. pop-container

역할: 모든 컴포넌트의 부모, 화면 뼈대

| 기능 | 설명 |
|------|------|
| 반응형 그리드 | 모바일/태블릿 자동 대응 |
| 플렉스 방향 | row, column, wrap |
| 간격 설정 | gap, padding |
| 배경/테두리 | 색상, 둥근모서리 |
| 스크롤 설정 | 가로/세로/없음 |

---

## 2. pop-tab-panel

역할: 정보 분류, 화면 공간 효율화

| 기능 | 설명 |
|------|------|
| 탭 모드 | 상단/하단/좌측 탭 |
| 아코디언 모드 | 접기/펼치기 |
| 아이콘 지원 | 탭별 아이콘 |
| 뱃지 표시 | 알림 개수 표시 |
| 기본 활성 탭 | 초기 선택 설정 |

---

## 3. pop-spacer (v4 전용)

역할: 빈 공간을 차지하여 레이아웃 정렬에 사용 (Figma, Webflow 등 업계 표준)

| 기능 | 설명 |
|------|------|
| 공간 채우기 | 남은 공간을 자동으로 채움 (`width: fill`) |
| 고정 크기 | 특정 크기의 빈 공간 (`width: fixed`) |
| 정렬 용도 | 컴포넌트를 오른쪽/가운데 정렬 |

### 사용 예시

```
[버튼A] [Spacer(fill)] [버튼B]     → 버튼B가 오른쪽 끝으로
[Spacer] [컴포넌트] [Spacer]       → 컴포넌트가 가운데로
[Spacer(fill)] [컴포넌트]          → 컴포넌트가 오른쪽으로
```

### 기본 설정

| 속성 | 기본값 |
|------|--------|
| width | fill (남은 공간 채움) |
| height | 48px (고정) |
| 디자인 모드 표시 | 점선 배경 + "빈 공간" 텍스트 |
| 실제 모드 | 완전히 투명 (공간만 차지) |

---

## 4. pop-break (v4 전용) 🆕

역할: Flexbox에서 강제 줄바꿈을 위한 컴포넌트 (업계 표준: Figma Auto Layout의 줄바꿈과 동일)

| 기능 | 설명 |
|------|------|
| 강제 줄바꿈 | `flex-basis: 100%`로 다음 컴포넌트를 새 줄로 이동 |
| 모드별 표시 | visibility 속성으로 특정 모드에서만 줄바꿈 적용 |
| 시각적 표시 | 디자인 모드에서만 점선으로 표시 |
| 실제 화면 | 높이 0px (완전히 보이지 않음) |

### 동작 원리

```
Flexbox wrap: true 상태에서
flex-basis: 100%를 가진 요소 → 전체 너비 차지 → 다음 요소는 자동으로 새 줄로 이동
```

### 사용 예시

```
[필드A] [필드B] [줄바꿈] [필드C] [필드D]

결과:
┌────────────────────┐
│ [필드A] [필드B]    │  ← 첫째 줄
│ [필드C] [필드D]    │  ← 둘째 줄 (줄바꿈 후)
└────────────────────┘
```

### 모드별 줄바꿈

```typescript
// 줄바꿈 컴포넌트 설정
{
  id: "break-1",
  type: "pop-break",
  visibility: {
    tablet_landscape: false,  // 태블릿: 줄바꿈 숨김 (한 줄)
    mobile_portrait: true,    // 모바일: 줄바꿈 표시 (두 줄)
  }
}

// 결과
태블릿: [A] [B] [C] [D]  (한 줄)
모바일: [A] [B]          (두 줄)
        [C] [D]
```

### 기본 설정

| 속성 | 기본값 |
|------|--------|
| width | fill (`flex-basis: 100%`) |
| height | 0px (높이 없음) |
| 디자인 모드 표시 | 점선 + "줄바꿈" 텍스트 (높이 16px) |
| 실제 모드 | 완전히 투명 (높이 0px) |
| flex-basis | 100% (핵심 속성) |

### CSS 구현

```css
/* 디자인 모드 */
.pop-break-design {
  flex-basis: 100%;
  width: 100%;
  height: 16px;
  border: 2px dashed #d1d5db;
  border-radius: 4px;
  display: flex;
  align-items: center;
  justify-content: center;
}

/* 실제 모드 */
.pop-break-runtime {
  flex-basis: 100%;
  width: 100%;
  height: 0;
}
```

### 업계 비교

| 서비스 | 줄바꿈 방식 |
|--------|------------|
| Figma Auto Layout | "Wrap" 설정 + 수동 줄 분리 |
| Webflow Flexbox | "Wrap" + 100% width spacer |
| Framer | "Break" 컴포넌트 |
| **POP v4** | **pop-break (flex-basis: 100%)** |

### 주의사항

- 컨테이너의 `wrap: true` 설정 필수
- wrap이 false면 줄바꿈 무시됨
- visibility로 모드별 제어 가능
- 디자인 모드에서만 시각적으로 보임

---

## 5. pop-data-table

역할: 대량 데이터 표시, 선택, 편집

| 기능 | 설명 |
|------|------|
| 가상 스크롤 | 대량 데이터 성능 |
| 행 선택 | 단일/다중 선택 |
| 인라인 편집 | 셀 직접 수정 |
| 정렬/필터 | 컬럼별 정렬, 검색 |
| 고정 컬럼 | 좌측 컬럼 고정 |
| 행 색상 조건 | 상태별 배경색 |
| 큰 글씨 모드 | POP 전용 가독성 |

---

## 4. pop-card-list

역할: 시각적 강조가 필요한 목록

| 기능 | 설명 |
|------|------|
| 카드 레이아웃 | 1열/2열/3열 |
| 이미지 표시 | 부품/제품 사진 |
| 상태 뱃지 | 진행중/완료/대기 |
| 진행률 바 | 작업 진척도 |
| 스와이프 액션 | 완료/삭제 (선택적) |
| 클릭 이벤트 | 상세 모달 연결 |

---

## 5. pop-kpi-gauge

역할: 목표 대비 실적 시각화

| 기능 | 설명 |
|------|------|
| 게이지 타입 | 원형/반원형/수평바 |
| 목표값 | 기준선 표시 |
| 현재값 | 실시간 바인딩 |
| 색상 구간 | 위험/경고/정상 |
| 단위 표시 | %, 개, 초 등 |
| 애니메이션 | 값 변경 시 전환 |
| 라벨 | 제목, 부제목 |

---

## 6. pop-status-indicator

역할: 설비/공정 상태 즉시 파악

| 기능 | 설명 |
|------|------|
| 표시 타입 | 원형/사각/아이콘 |
| 상태 매핑 | 값 -> 색상/아이콘 자동 |
| 색상 설정 | 상태별 커스텀 |
| 크기 | S/M/L/XL |
| 깜빡임 | 알람 상태 강조 |
| 라벨 위치 | 상단/하단/우측 |
| 그룹 표시 | 여러 상태 한 줄 |

---

## 7. pop-number-pad

역할: 장갑 착용 상태 수량 입력

| 기능 | 설명 |
|------|------|
| 큰 버튼 | 최소 48px (1.5cm) |
| 레이아웃 | 전화기식/계산기식 |
| 소수점 | 허용/불허 |
| 음수 | 허용/불허 |
| 최소/최대값 | 범위 제한 |
| 단위 표시 | 개, kg, m 등 |
| 빠른 증감 | +1, +10, +100 버튼 |
| 진동 피드백 | 터치 확인 |
| 클리어 | 전체 삭제, 한 자리 삭제 |

---

## 8. pop-barcode-scanner

역할: 자재 투입, 로트 추적

| 기능 | 설명 |
|------|------|
| 카메라 스캔 | 모바일 카메라 연동 |
| 외부 스캐너 | USB/블루투스 연동 |
| 스캔 타입 | 바코드/QR/RFID |
| 연속 스캔 | 다중 입력 모드 |
| 이력 표시 | 최근 스캔 목록 |
| 유효성 검증 | 포맷 체크 |
| 자동 조회 | 스캔 후 API 연동 |
| 소리/진동 | 스캔 성공 피드백 |

---

## 9. pop-form-field

역할: 텍스트, 선택, 날짜 등 범용 입력

| 기능 | 설명 |
|------|------|
| 입력 타입 | text/number/date/time/select |
| 라벨 | 상단/좌측/플로팅 |
| 필수 표시 | 별표, 색상 |
| 유효성 검증 | 실시간 체크 |
| 에러 메시지 | 하단 표시 |
| 비활성화 | 읽기 전용 모드 |
| 큰 사이즈 | POP 전용 높이 |
| 도움말 | 툴팁/하단 설명 |

---

## 10. pop-action-button

역할: 작업 실행, 상태 변경

| 기능 | 설명 |
|------|------|
| 크기 | S/M/L/XL/전체너비 |
| 스타일 | primary/secondary/danger/success |
| 아이콘 | 좌측/우측/단독 |
| 로딩 상태 | 스피너 표시 |
| 비활성화 | 조건부 |
| 확인 다이얼로그 | 위험 작업 전 확인 |
| 길게 누르기 | 특수 동작 (선택적) |
| 뱃지 | 개수 표시 |

---

## 11. pop-timer

역할: 사이클 타임, 비가동 시간 측정

| 기능 | 설명 |
|------|------|
| 모드 | 스톱워치/카운트다운 |
| 시작/정지/리셋 | 기본 제어 |
| 랩 타임 | 구간 기록 |
| 목표 시간 | 초과 시 알림 |
| 표시 형식 | HH:MM:SS / MM:SS |
| 크기 | 작은/중간/큰 |
| 배경 색상 | 상태별 변경 |
| 자동 시작 | 조건부 트리거 |

---

## 12. pop-alarm-list

역할: 이상 상황 알림 및 확인

| 기능 | 설명 |
|------|------|
| 우선순위 | 긴급/경고/정보 |
| 색상 구분 | 레벨별 배경색 |
| 시간 표시 | 발생 시각 |
| 확인(Ack) | 알람 인지 처리 |
| 필터 | 미확인만/전체 |
| 정렬 | 시간순/우선순위순 |
| 상세 보기 | 클릭 시 모달 |
| 소리 알림 | 신규 알람 |

---

## 13. pop-process-flow

역할: 전체 공정 현황 시각화

| 기능 | 설명 |
|------|------|
| 노드 타입 | 공정/검사/대기 |
| 연결선 | 화살표, 분기 |
| 현재 위치 | 강조 표시 |
| 상태 색상 | 완료/진행/대기 |
| 클릭 이벤트 | 공정 상세 이동 |
| 가로/세로 | 방향 설정 |
| 축소/확대 | 핀치 줌 |
| 진행률 | 전체 대비 현재 |

---

## 커버 가능한 시나리오

이 13개 컴포넌트 조합으로 대응 가능한 화면:

- 작업 지시 화면
- 실적 입력 화면
- 품질 검사 화면
- 설비 모니터링 대시보드
- 자재 투입/출고 화면
- 알람 관리 화면
- 공정 현황판

---

## 기존 컴포넌트 재사용 가능 목록

| POP 컴포넌트 | 기존 컴포넌트 | 수정 필요 |
|-------------|--------------|----------|
| pop-data-table | v2-table-widget | 큰 글씨 모드 추가 |
| pop-form-field | v2-input-widget, v2-select-widget | 큰 사이즈 옵션 |
| pop-action-button | v2-button-widget | 크기/확인 다이얼로그 |
| pop-tab-panel | tab-widget | POP 스타일 적용 |

---

## Phase 3 업데이트 (2026-02-04) 🆕

### 추가된 컴포넌트

#### pop-break (줄바꿈)
- **역할**: Flexbox에서 강제 줄바꿈
- **핵심 기술**: `flex-basis: 100%`
- **모드별 제어**: visibility 속성 지원
- **시각적 표시**: 디자인 모드에서만 점선 표시 (실제 높이 0px)

### 모든 컴포넌트 공통 추가 속성

#### visibility (모드별 표시/숨김)
```typescript
visibility?: {
  tablet_landscape?: boolean;
  tablet_portrait?: boolean;
  mobile_landscape?: boolean;
  mobile_portrait?: boolean;
}
```

**사용 예시**:
```typescript
// 모바일 전용 버튼
{
  type: "pop-action-button",
  visibility: {
    tablet_landscape: false,
    mobile_portrait: true,
  }
}
```

### 참고 문서
- [decisions/002-phase3-visibility-break.md](./decisions/002-phase3-visibility-break.md) - 상세 설계
- [V4_UNIFIED_DESIGN_SPEC.md](./V4_UNIFIED_DESIGN_SPEC.md) - v4 통합 설계

---

*최종 업데이트: 2026-02-04 (Phase 3 완료)*