462 lines
12 KiB
Markdown
462 lines
12 KiB
Markdown
# 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 완료)*
|