kjs
/
ERP-node
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

POP v4 제약조건 기반 레이아웃 타입 정의 및 문서 구조 재정리 

- v4 타입 추가: PopLayoutDataV4, PopContainerV4, PopSizeConstraintV4
- 핵심 변경: 4모드 위치 지정 → 단일 소스 규칙 기반 (fill/fixed/hug)
- 생성 함수: createEmptyPopLayoutV4(), isV4Layout() 타입 가드
- 문서 정리: popdocs/ 폴더로 통합, 기존 문서 archive/로 이동
This commit is contained in:
SeongHyun Kim 2026-02-04 10:14:05 +09:00
parent de2163bcef
commit 223f5c0251
16 changed files with 2448 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

176
frontend/components/pop/designer/types/pop-layout.ts
View File

@ -1,9 +1,173 @@
// POP 디자이너 레이아웃 타입 정의
// v3.0: 섹션 제거, 컴포넌트 직접 배치
// 그리드 기반 반응형 레이아웃 (픽셀 좌표 없음, 그리드 셀 기반)
// v4.0: 제약조건 기반, 단일 소스 → 자동 적응 (Flexbox)
// v3.0: 4모드 그리드 기반 (CSS Grid)
// ========================================
// 레이아웃 모드 키 (4가지)
// v4.0 제약조건 기반 레이아웃
// ========================================
// 핵심: 1번 설계 → 모든 화면 자동 적응
// - 위치(col/row) 대신 규칙(fill/fixed/hug) 설정
// - Flexbox로 렌더링, 자동 줄바꿈
/**
* v4 레이아웃 (반응형)
* - 단일 소스: 4모드 따로 설계 X
* - 규칙 기반: 컴포넌트가 어떻게 반응할지 정의
*/
export interface PopLayoutDataV4 {
version: "pop-4.0";
// 루트 컨테이너 (스택)
root: PopContainerV4;
// 컴포넌트 정의 (ID → 정의)
components: Record<string, PopComponentDefinitionV4>;
// 데이터 흐름 (기존과 동일)
dataFlow: PopDataFlow;
// 전역 설정
settings: PopGlobalSettingsV4;
// 메타데이터
metadata?: PopLayoutMetadata;
}
/**
* v4 컨테이너 (스택)
* - Flexbox 기반
* - 자식: 컴포넌트 ID 또는 중첩 컨테이너
*/
export interface PopContainerV4 {
id: string;
type: "stack";
// 방향: 가로 또는 세로
direction: "horizontal" | "vertical";
// 줄바꿈 허용
wrap: boolean;
// 간격 (px)
gap: number;
// 정렬
alignItems: "start" | "center" | "end" | "stretch";
justifyContent: "start" | "center" | "end" | "space-between";
// 패딩 (px)
padding?: number;
// 반응형 규칙 (선택)
responsive?: PopResponsiveRuleV4[];
// 자식 요소
children: (string | PopContainerV4)[];
}
/**
* 반응형 규칙
* - 특정 너비 이하에서 속성 변경
*/
export interface PopResponsiveRuleV4 {
// 이 너비 이하에서 적용 (px)
breakpoint: number;
// 변경할 속성들
direction?: "horizontal" | "vertical";
gap?: number;
hidden?: boolean; // 컨테이너 숨김
}
/**
* v4 컴포넌트 정의
* - 크기 제약 기반
*/
export interface PopComponentDefinitionV4 {
id: string;
type: PopComponentType;
label?: string;
// 크기 제약 (핵심)
size: PopSizeConstraintV4;
// 개별 정렬 (컨테이너 설정 덮어쓰기)
alignSelf?: "start" | "center" | "end" | "stretch";
// 반응형 숨김
hideBelow?: number; // 이 너비 이하에서 숨김
// 기존 속성
dataBinding?: PopDataBinding;
style?: PopStylePreset;
config?: PopComponentConfig;
}
/**
* 크기 제약
* - fixed: 고정 px
* - fill: 남은 공간 채움
* - hug: 내용에 맞춤
*/
export interface PopSizeConstraintV4 {
width: "fixed" | "fill" | "hug";
height: "fixed" | "fill" | "hug";
// fixed일 때 값
fixedWidth?: number;
fixedHeight?: number;
// 최소/최대
minWidth?: number;
maxWidth?: number;
minHeight?: number;
}
/**
* v4 전역 설정
*/
export interface PopGlobalSettingsV4 {
// 터치 최소 크기 (px)
touchTargetMin: number; // 기본 48
// 모드
mode: "normal" | "industrial"; // industrial: 터치 60px
// 기본 간격
defaultGap: number; // 기본 8
// 기본 패딩
defaultPadding: number; // 기본 16
}
// ========================================
// v4 생성 함수
// ========================================
export const createEmptyPopLayoutV4 = (): PopLayoutDataV4 => ({
version: "pop-4.0",
root: {
id: "root",
type: "stack",
direction: "vertical",
wrap: false,
gap: 8,
alignItems: "stretch",
justifyContent: "start",
padding: 16,
children: [],
},
components: {},
dataFlow: { connections: [] },
settings: {
touchTargetMin: 48,
mode: "normal",
defaultGap: 8,
defaultPadding: 16,
},
});
// ========================================
// 레이아웃 모드 키 (v3용)
// ========================================
export type PopLayoutModeKey =
| "tablet_landscape" // 태블릿 가로 (1024x768)
@ -127,7 +291,11 @@ export interface PopLayoutDataV1 {
// 통합 타입
// ========================================
export type PopLayoutData = PopLayoutDataV1 | PopLayoutDataV2 | PopLayoutDataV3;
export type PopLayoutData = PopLayoutDataV1 | PopLayoutDataV2 | PopLayoutDataV3 | PopLayoutDataV4;
export function isV4Layout(data: PopLayoutData): data is PopLayoutDataV4 {
return data.version === "pop-4.0";
}
export function isV3Layout(data: PopLayoutData): data is PopLayoutDataV3 {
return data.version === "pop-3.0";

108
popdocs/CHANGELOG.md Normal file
View File

@ -0,0 +1,108 @@
# POP 변경 이력
형식: [Keep a Changelog](https://keepachangelog.com/)
---
## [미출시]
- v4 디자이너 UI 연결
- Tier 2, 3 컴포넌트
---
## [2026-02-04]
### 오늘 목표
POP 화면을 만들 수 있는 환경 완성 (타입 + 렌더러 + 기본 컴포넌트)
### Added
- **v4 타입 정의** (간결 버전)
- `PopLayoutDataV4` - 단일 소스 레이아웃
- `PopContainerV4` - 스택 컨테이너 (direction, wrap, gap, alignItems)
- `PopComponentDefinitionV4` - 크기 제약 기반 (size: fixed/fill/hug)
- `PopSizeConstraintV4` - 크기 규칙
- `PopResponsiveRuleV4` - 반응형 규칙 (breakpoint별 변경)
- `PopGlobalSettingsV4` - 전역 설정
- `createEmptyPopLayoutV4()` - 생성 함수
- `isV4Layout()` - 타입 가드
### 진행중
- v4 렌더러 (`PopFlexRenderer`)
- 기본 컴포넌트 (PopButton, PopInput, PopLabel)
---
## [2026-02-04] (earlier)
### Added
- 저장/조회 시스템 구축
- rangraph: AI 장기 기억 (시맨틱 검색, 요약)
- popdocs: 상세 기록 (파일 기반, 히스토리)
- 이중 저장 체계로 검색 + 기록 분리
### Changed
- popdocs 문서 구조 정리
- README.md: 저장/조회 규칙 추가
- 기존 문서 archive/로 이동
- 문서 관리 전략 확정
- 저장 시: 파일 형식 자동 파악 → 형식 맞춰 추가 → rangraph 요약
- 조회 시: rangraph 시맨틱 검색
### Removed
- .cursorrules 변경 계획 철회 (Git 커밋 영향)
---
## [2026-02-03]
### Added
- v4 제약조건 기반 레이아웃 계획
- 단일 소스 + 자동 적응
- 3가지 규칙 (크기, 배치, 반응형)
- ADR: `decisions/001-v4-constraint-based.md`
---
## [2026-02-02]
### Fixed
- 캔버스 rowSpan 문제
- 원인: gridTemplateRows 고정 px
- 해결: `1fr` 사용
---
## [2026-02-01]
### Fixed
- 4모드 자동 전환 문제
- 해결: useResponsiveMode 훅 추가
---
## [2026-01-31]
### Added
- v3 섹션 제거, 순수 그리드 구조
- 4개 모드 독립 그리드
---
## [2026-01-30]
### Added
- POP 디자이너 기본 구조
- PopDesigner, PopCanvas 컴포넌트
---
## [2026-01-29]
### Added
- screen_layouts_pop 테이블
- POP 레이아웃 API (CRUD)
---
*최신이 위, 시간순 역순*

91
popdocs/PLAN.md Normal file
View File

@ -0,0 +1,91 @@
# POP 개발 계획
---
## 오늘 목표 (2026-02-04)
**POP 화면을 만들 수 있는 환경 완성**
### 필요한 것
1. **v4 타입 정의** - 완료
2. **v4 렌더러** - Flexbox로 화면에 표시
3. **기본 컴포넌트** - 실제 배치할 요소들
4. **디자이너 UI 연결** - v4 모드로 설계 가능
### 작업 순서
```
[v4 타입] → [렌더러] → [컴포넌트] → [디자이너 연결]
완료 진행 대기 대기
```
---
## 현재 진행
### v4 타입 정의 (완료)
- [x] `PopLayoutDataV4` - 단일 소스 레이아웃
- [x] `PopContainerV4` - 스택 컨테이너
- [x] `PopSizeConstraintV4` - 크기 규칙 (fixed/fill/hug)
- [x] `PopResponsiveRuleV4` - 반응형 규칙
- [x] `createEmptyPopLayoutV4()` - 생성 함수
- [x] `isV4Layout()` - 타입 가드
### v4 렌더러 (진행)
- [ ] `PopFlexRenderer` - Flexbox 기반 렌더링
- [ ] 컨테이너 재귀 렌더링
- [ ] 반응형 규칙 적용 (breakpoint)
- [ ] 컴포넌트 숨김 처리 (hideBelow)
### 기본 컴포넌트 (대기)
- [ ] `PopButton` - 터치 버튼
- [ ] `PopInput` - 텍스트 입력
- [ ] `PopLabel` - 텍스트 표시
---
## v3 vs v4 비교
| | v3 (기존) | v4 (새로운) |
|---|---|---|
| 설계 | 4모드 각각 | 1번만 |
| 데이터 | col, row 위치 | 규칙 (fill/fixed/hug) |
| 렌더링 | CSS Grid | Flexbox |
| 반응형 | 수동 | 자동 + 규칙 |
---
## 컴포넌트 로드맵
### Tier 1: Primitive (기본)
| 컴포넌트 | 용도 | 상태 |
|----------|------|------|
| PopButton | 터치 버튼 | 대기 |
| PopInput | 텍스트 입력 | 대기 |
| PopLabel | 텍스트 표시 | 대기 |
| PopBadge | 상태 배지 | 계획 |
### Tier 2: Compound (조합)
| 컴포넌트 | 용도 | 상태 |
|----------|------|------|
| PopFormField | 라벨 + 입력 | 계획 |
| PopCard | 카드 컨테이너 | 계획 |
| PopListItem | 목록 항목 | 계획 |
### Tier 3: Complex (복합)
| 컴포넌트 | 용도 | 상태 |
|----------|------|------|
| PopScanner | 바코드/QR 스캔 | 계획 |
| PopNumpad | 숫자 키패드 | 계획 |
| PopDataList | 페이징 목록 | 계획 |
---
*최종 업데이트: 2026-02-04*

90
popdocs/README.md Normal file
View File

@ -0,0 +1,90 @@
# POP 화면 시스템
> Point of Production - 현장 작업자용 모바일/태블릿 화면
---
## Quick Reference
### 주요 경로
| 용도 | 경로 |
|------|------|
| 뷰어 | `/pop/screens/{screenId}` |
| 관리 | `/admin/screenMng/popScreenMngList` |
| API | `/api/screen-management/layout-pop/:screenId` |
### 핵심 파일
| 작업 | 파일 |
|------|------|
| 타입 | `frontend/components/pop/designer/types/pop-layout.ts` |
| 렌더러 | `frontend/components/pop/designer/renderers/` |
| 디자이너 | `frontend/components/pop/designer/PopDesigner.tsx` |
### 현재 상태
- **버전**: v3.0 (4모드 그리드)
- **다음**: v4.0 (제약조건 기반) - 계획
---
## 문서 구조
| 파일 | 용도 |
|------|------|
| [SPEC.md](./SPEC.md) | 기술 스펙 |
| [PLAN.md](./PLAN.md) | 계획/로드맵 |
| [CHANGELOG.md](./CHANGELOG.md) | 변경 이력 |
| [decisions/](./decisions/) | 중요 결정 기록 (ADR) |
| [components-spec.md](./components-spec.md) | 컴포넌트 상세 |
| [archive/](./archive/) | 이전 문서 |
---
## 저장/조회 시스템
### 역할 분담
| 저장소 | 역할 | 특징 |
|--------|------|------|
| **rangraph** | AI 장기 기억 | 시맨틱 검색, 요약 저장 |
| **popdocs** | 상세 기록 | 파일 기반, 히스토리 |
### 저장 요청
| 요청 예시 | AI 행동 |
|----------|--------|
| "@CHANGELOG.md 오늘 작업 정리해줘" | 파일 형식 맞춰 추가 + rangraph 요약 |
| "이 결정 저장해줘" | rangraph save_decision + decisions/ ADR |
| "해결됐어" | rangraph save_lesson + CHANGELOG Fixed |
| "작업 완료" | rangraph workflow_submit + CHANGELOG Added |
### 조회 요청
| 요청 예시 | AI 행동 |
|----------|--------|
| "어제 뭐했지?" | rangraph 검색 |
| "지금 뭐하는 중이었지?" | rangraph workflow_status |
| "이 버그 전에도 있었어?" | rangraph search_memory |
| "v4 관련 작업들" | rangraph search_memory "v4" |
---
## v4 핵심 (요약)
```
v3: 4개 모드 각각 위치 설정 → 4배 작업량
v4: 3가지 규칙만 설정 → 자동 적응
규칙:
1. 크기: fixed(고정) / fill(채움) / hug(맞춤)
2. 배치: direction, wrap, gap
3. 반응형: breakpoint별 변경
```
상세: [SPEC.md](./SPEC.md)
---
*최종 업데이트: 2026-02-04*

121
popdocs/SPEC.md Normal file
View File

@ -0,0 +1,121 @@
# POP 기술 스펙
---
## v4 핵심 규칙 (3가지)
### 1. 크기 규칙 (Size)
| 모드 | 설명 | 예시 |
|------|------|------|
| `fixed` | 고정 px | 버튼 48px |
| `fill` | 부모 채움 | 입력창 100% |
| `hug` | 내용 맞춤 | 라벨 |
### 2. 배치 규칙 (Layout)
| 항목 | 옵션 |
|------|------|
| direction | horizontal / vertical |
| wrap | true / false |
| gap | 8 / 16 / 24 px |
| alignItems | start / center / end / stretch |
### 3. 반응형 규칙 (Responsive)
```typescript
{
direction: "horizontal",
responsive: [{ breakpoint: 768, direction: "vertical" }]
}
```
---
## 크기 프리셋
### 터치 요소
| 요소 | 일반 | 산업 |
|------|-----|------|
| 버튼 높이 | 48px | 60px |
| 입력창 높이 | 48px | 56px |
| 터치 영역 | 48px | 60px |
### 폰트 (clamp)
| 용도 | 범위 | CSS |
|------|-----|-----|
| 본문 | 14-18px | `clamp(14px, 1.5vw, 18px)` |
| 제목 | 18-28px | `clamp(18px, 2.5vw, 28px)` |
### 간격
| 이름 | 값 | 용도 |
|------|---|-----|
| sm | 8px | 요소 내부 |
| md | 16px | 컴포넌트 간 |
| lg | 24px | 섹션 간 |
---
## 반응형 원칙
```
누르는 것 → 고정 (48px)
읽는 것 → 범위 (clamp)
담는 것 → 비율 (%)
```
---
## 데이터 구조
### v3 (현재)
```typescript
interface PopLayoutDataV3 {
version: "pop-3.0";
layouts: {
tablet_landscape: { componentPositions: Record<string, GridPosition> };
// ... 4개 모드
};
components: Record<string, PopComponentDefinition>;
}
```
### v4 (계획)
```typescript
interface PopLayoutDataV4 {
version: "pop-4.0";
root: PopContainer;
components: Record<string, PopComponentDefinitionV4>;
}
interface PopContainer {
type: "stack";
direction: "horizontal" | "vertical";
children: (string | PopContainer)[];
responsive?: { breakpoint: number; direction?: string }[];
}
```
---
## Troubleshooting
### 캔버스 rowSpan 문제
- **증상**: 컴포넌트가 얇게 보임
- **원인**: gridTemplateRows 고정 px
- **해결**: `1fr` 사용
### 4모드 전환 안 됨
- **증상**: 크기 줄여도 레이아웃 유지
- **해결**: useResponsiveMode 훅 사용
---
*상세 archive 참조: `archive/V4_CORE_RULES.md`, `archive/SIZE_PRESETS.md`*

0
BUGFIX_CANVAS_ROWS.md → popdocs/archive/BUGFIX_CANVAS_ROWS.md
View File

389
popdocs/archive/COMPONENT_ROADMAP.md Normal file
View File

@ -0,0 +1,389 @@
# POP 컴포넌트 로드맵
## 큰 그림: 3단계 접근
```
┌─────────────────────────────────────────────────────────────────┐
│ │
│ 1단계: 기초 블록 2단계: 조합 블록 3단계: 완성 화면 │
│ ─────────────── ─────────────── ─────────────── │
│ │
│ [버튼] [입력창] [폼 그룹] [작업지시 화면] │
│ [아이콘] [라벨] → [카드] → [실적입력 화면] │
│ [뱃지] [로딩] [리스트] [모니터링 대시보드] │
│ [테이블] │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 1단계: 기초 블록 (Primitive)
가장 작은 단위. 다른 곳에서 재사용됩니다.
### 필수 기초 블록
| 컴포넌트 | 역할 | 우선순위 |
|---------|------|---------|
| `PopButton` | 모든 버튼 | 1 |
| `PopInput` | 텍스트 입력 | 1 |
| `PopLabel` | 라벨/제목 | 1 |
| `PopIcon` | 아이콘 표시 | 1 |
| `PopBadge` | 상태 뱃지 | 2 |
| `PopLoading` | 로딩 스피너 | 2 |
| `PopDivider` | 구분선 | 3 |
### PopButton 예시
```typescript
interface PopButtonProps {
children: React.ReactNode;
variant: "primary" | "secondary" | "danger" | "success";
size: "sm" | "md" | "lg" | "xl";
disabled?: boolean;
loading?: boolean;
icon?: string;
fullWidth?: boolean;
onClick?: () => void;
}
// 사용
<PopButton variant="primary" size="lg">
작업 완료
</PopButton>
```
### PopInput 예시
```typescript
interface PopInputProps {
type: "text" | "number" | "date" | "time";
value: string | number;
onChange: (value: string | number) => void;
label?: string;
placeholder?: string;
required?: boolean;
error?: string;
size: "md" | "lg"; // POP은 lg 기본
}
// 사용
<PopInput
type="number"
label="수량"
size="lg"
value={qty}
onChange={setQty}
/>
```
---
## 2단계: 조합 블록 (Compound)
기초 블록을 조합한 중간 단위.
### 조합 블록 목록
| 컴포넌트 | 구성 | 용도 |
|---------|------|-----|
| `PopFormField` | Label + Input + Error | 폼 입력 그룹 |
| `PopCard` | Container + Header + Body | 정보 카드 |
| `PopListItem` | Container + Content + Action | 리스트 항목 |
| `PopNumberPad` | Grid + Buttons | 숫자 입력 |
| `PopStatusBox` | Icon + Label + Value | 상태 표시 |
### PopFormField 예시
```typescript
// 기초 블록 조합
function PopFormField({ label, required, error, children }) {
return (
<div className="pop-form-field">
<PopLabel required={required}>{label}</PopLabel>
{children}
{error && <span className="error">{error}</span>}
</div>
);
}
// 사용
<PopFormField label="품번" required error={errors.itemCode}>
<PopInput type="text" value={itemCode} onChange={setItemCode} />
</PopFormField>
```
### PopCard 예시
```typescript
function PopCard({ title, badge, children, onClick }) {
return (
<div className="pop-card" onClick={onClick}>
<div className="pop-card-header">
<PopLabel size="lg">{title}</PopLabel>
{badge && <PopBadge>{badge}</PopBadge>}
</div>
<div className="pop-card-body">
{children}
</div>
</div>
);
}
// 사용
<PopCard title="작업지시 #1234" badge="진행중">
<p>목표 수량: 100개</p>
<p>완료 수량: 45개</p>
</PopCard>
```
---
## 3단계: 복합 컴포넌트 (Complex)
비즈니스 로직이 포함된 완성형.
### 복합 컴포넌트 목록
| 컴포넌트 | 기능 | 데이터 |
|---------|------|-------|
| `PopDataTable` | 대량 데이터 표시/편집 | API 연동 |
| `PopCardList` | 카드 형태 리스트 | API 연동 |
| `PopBarcodeScanner` | 바코드/QR 스캔 | 카메라/외부장치 |
| `PopKpiGauge` | KPI 게이지 | 실시간 데이터 |
| `PopAlarmList` | 알람 목록 | 웹소켓 |
| `PopProcessFlow` | 공정 흐름도 | 공정 데이터 |
### PopDataTable 예시
```typescript
interface PopDataTableProps {
// 데이터
data: any[];
columns: Column[];
// 기능
selectable?: boolean;
editable?: boolean;
sortable?: boolean;
// 반응형 (자동)
responsiveColumns?: {
tablet: string[];
mobile: string[];
};
// 이벤트
onRowClick?: (row: any) => void;
onSelectionChange?: (selected: any[]) => void;
}
// 사용
<PopDataTable
data={workOrders}
columns={[
{ key: "orderNo", label: "지시번호" },
{ key: "itemName", label: "품명" },
{ key: "qty", label: "수량", align: "right" },
{ key: "status", label: "상태" },
]}
responsiveColumns={{
tablet: ["orderNo", "itemName", "qty", "status"],
mobile: ["orderNo", "qty"], // 모바일은 2개만
}}
onRowClick={(row) => openDetail(row.id)}
/>
```
---
## 개발 순서 제안
### Phase 1: 기초 (1-2주)
```
Week 1:
- PopButton (모든 버튼의 기반)
- PopInput (모든 입력의 기반)
- PopLabel
- PopIcon
Week 2:
- PopBadge
- PopLoading
- PopDivider
```
### Phase 2: 조합 (2-3주)
```
Week 3:
- PopFormField (폼의 기본 단위)
- PopCard (카드의 기본 단위)
Week 4:
- PopListItem
- PopStatusBox
- PopNumberPad
Week 5:
- PopModal
- PopToast
```
### Phase 3: 복합 (3-4주)
```
Week 6-7:
- PopDataTable (가장 복잡)
- PopCardList
Week 8-9:
- PopBarcodeScanner
- PopKpiGauge
- PopAlarmList
- PopProcessFlow
```
---
## 컴포넌트 설계 원칙
### 1. 크기는 외부에서 제어
```typescript
// 좋음: 크기를 props로 받음
<PopButton size="lg">확인</PopButton>
// 나쁨: 내부에서 크기 고정
<button style={{ height: "48px" }}>확인</button>
```
### 2. 최소 크기는 내부에서 보장
```typescript
// 컴포넌트 내부
const styles = {
minHeight: 48, // 터치 최소 크기 보장
minWidth: 80,
};
```
### 3. 반응형은 자동
```typescript
// 좋음: 화면 크기에 따라 자동 조절
<PopFormField label="이름">
<PopInput />
</PopFormField>
// 나쁨: 모드별로 다른 컴포넌트
{isMobile ? <MobileInput /> : <TabletInput />}
```
### 4. 데이터와 UI 분리
```typescript
// 좋음: 데이터 로직은 훅으로
const { data, loading, error } = useWorkOrders();
<PopDataTable data={data} loading={loading} />
// 나쁨: 컴포넌트 안에서 fetch
function PopDataTable() {
useEffect(() => {
fetch('/api/work-orders')...
}, []);
}
```
---
## 폴더 구조 제안
```
frontend/components/pop/
├── primitives/ # 1단계: 기초 블록
│ ├── PopButton.tsx
│ ├── PopInput.tsx
│ ├── PopLabel.tsx
│ ├── PopIcon.tsx
│ ├── PopBadge.tsx
│ ├── PopLoading.tsx
│ └── index.ts
│
├── compounds/ # 2단계: 조합 블록
│ ├── PopFormField.tsx
│ ├── PopCard.tsx
│ ├── PopListItem.tsx
│ ├── PopNumberPad.tsx
│ ├── PopStatusBox.tsx
│ └── index.ts
│
├── complex/ # 3단계: 복합 컴포넌트
│ ├── PopDataTable/
│ │ ├── PopDataTable.tsx
│ │ ├── PopTableHeader.tsx
│ │ ├── PopTableRow.tsx
│ │ └── index.ts
│ ├── PopCardList/
│ ├── PopBarcodeScanner/
│ └── index.ts
│
├── hooks/ # 공용 훅
│ ├── usePopTheme.ts
│ ├── useResponsiveSize.ts
│ └── useTouchFeedback.ts
│
└── styles/ # 공용 스타일
├── pop-variables.css
└── pop-base.css
```
---
## 스타일 변수
```css
/* pop-variables.css */
:root {
/* 터치 크기 */
--pop-touch-min: 48px;
--pop-touch-industrial: 60px;
/* 폰트 크기 */
--pop-font-body: clamp(14px, 1.5vw, 18px);
--pop-font-heading: clamp(18px, 2.5vw, 28px);
--pop-font-caption: clamp(12px, 1vw, 14px);
/* 간격 */
--pop-gap-sm: 8px;
--pop-gap-md: 16px;
--pop-gap-lg: 24px;
/* 색상 */
--pop-primary: #2563eb;
--pop-success: #16a34a;
--pop-warning: #f59e0b;
--pop-danger: #dc2626;
/* 고대비 (야외용) */
--pop-high-contrast-bg: #000000;
--pop-high-contrast-fg: #ffffff;
}
```
---
## 다음 단계
1. **기초 블록부터 시작**: PopButton, PopInput 먼저 만들기
2. **스토리북 설정**: 컴포넌트별 문서화
3. **테스트**: 터치 크기, 반응형 확인
4. **디자이너 연동**: v4 레이아웃 시스템과 통합
---
*최종 업데이트: 2026-02-03*

0
POPREADME.md → popdocs/archive/POPREADME.md
View File

0
POPUPDATE.md → popdocs/archive/POPUPDATE.md
View File

760
popdocs/archive/POP_V4_CONSTRAINT_SYSTEM_PLAN.md Normal file
View File

@ -0,0 +1,760 @@
# POP v4.0 제약조건 기반 시스템 구현 계획
## 1. 현재 시스템 분석
### 1.1 현재 구조 (v3.0)
```typescript
// 4개 모드별 그리드 위치 기반
interface PopLayoutDataV3 {
version: "pop-3.0";
layouts: {
tablet_landscape: { componentPositions: Record<string, GridPosition> };
tablet_portrait: { componentPositions: Record<string, GridPosition> };
mobile_landscape: { componentPositions: Record<string, GridPosition> };
mobile_portrait: { componentPositions: Record<string, GridPosition> };
};
components: Record<string, PopComponentDefinition>;
// ...
}
interface GridPosition {
col: number; // 1-based
row: number; // 1-based
colSpan: number;
rowSpan: number;
}
```
### 1.2 현재 문제점
1. **4배 작업량**: 4개 모드 각각 설계 필요
2. **수동 동기화**: 컴포넌트 추가/삭제 시 4모드 수동 동기화
3. **그리드 한계**: col/row 기반이라 자동 재배치 불가
4. **반응형 미흡**: 화면 크기 변화에 자동 적응 불가
5. **디바이스 차이 무시**: 태블릿/모바일 물리적 크기 차이 고려 안됨
---
## 2. 새로운 시스템 설계 (v4.0)
### 2.1 핵심 철학
```
"하나의 레이아웃 설계 → 제약조건 설정 → 모든 화면 자동 적응"
```
- **단일 소스**: 1개 레이아웃만 설계
- **제약조건 기반**: 컴포넌트가 "어떻게 반응할지" 규칙 정의
- **Flexbox 렌더링**: CSS Grid에서 Flexbox 기반으로 전환
- **자동 줄바꿈**: 공간 부족 시 자동 재배치
### 2.2 새로운 데이터 구조
```typescript
// v4.0 레이아웃
interface PopLayoutDataV4 {
version: "pop-4.0";
// 루트 컨테이너
root: PopContainer;
// 컴포넌트 정의 (ID → 정의)
components: Record<string, PopComponentDefinitionV4>;
// 데이터 흐름
dataFlow: PopDataFlow;
// 전역 설정
settings: PopGlobalSettingsV4;
// 메타데이터
metadata?: PopLayoutMetadata;
}
```
### 2.3 컨테이너 (스택)
```typescript
// 컨테이너: 컴포넌트들을 담는 그룹
interface PopContainer {
id: string;
type: "stack";
// 스택 방향
direction: "horizontal" | "vertical";
// 줄바꿈 허용
wrap: boolean;
// 요소 간 간격
gap: number;
// 정렬
alignItems: "start" | "center" | "end" | "stretch";
justifyContent: "start" | "center" | "end" | "space-between" | "space-around";
// 패딩
padding?: {
top: number;
right: number;
bottom: number;
left: number;
};
// 반응형 규칙 (선택)
responsive?: {
// 브레이크포인트 (이 너비 이하에서 적용)
breakpoint: number;
// 변경할 방향
direction?: "horizontal" | "vertical";
// 변경할 간격
gap?: number;
}[];
// 자식 요소 (컴포넌트 ID 또는 중첩 컨테이너)
children: (string | PopContainer)[];
}
```
### 2.4 컴포넌트 제약조건
```typescript
interface PopComponentDefinitionV4 {
id: string;
type: PopComponentType;
label?: string;
// ===== 크기 제약 (핵심) =====
size: {
// 너비 모드
width: "fixed" | "fill" | "hug";
// 높이 모드
height: "fixed" | "fill" | "hug";
// 고정 크기 (width/height가 fixed일 때)
fixedWidth?: number;
fixedHeight?: number;
// 최소/최대 크기
minWidth?: number;
maxWidth?: number;
minHeight?: number;
maxHeight?: number;
// 비율 (fill일 때, 같은 컨테이너 내 다른 요소와의 비율)
flexGrow?: number; // 기본 1
flexShrink?: number; // 기본 1
};
// ===== 정렬 =====
alignSelf?: "start" | "center" | "end" | "stretch";
// ===== 여백 =====
margin?: {
top: number;
right: number;
bottom: number;
left: number;
};
// ===== 모바일 스케일 (선택) =====
// 모바일에서 컴포넌트를 더 크게 표시
mobileScale?: number; // 기본 1.0, 예: 1.2 = 20% 더 크게
// ===== 기존 속성 =====
dataBinding?: PopDataBinding;
style?: PopStylePreset;
config?: PopComponentConfig;
}
```
### 2.5 크기 모드 설명
| 모드 | 설명 | CSS 변환 |
|------|------|----------|
| `fixed` | 고정 크기 (px) | `width: {fixedWidth}px` |
| `fill` | 부모 공간 채우기 | `flex: {flexGrow} {flexShrink} 0` |
| `hug` | 내용에 맞춤 | `flex: 0 0 auto` |
### 2.6 전역 설정
```typescript
interface PopGlobalSettingsV4 {
// 기본 터치 타겟 크기
touchTargetMin: number; // 48px
// 모드 (일반/산업현장)
mode: "normal" | "industrial";
// 기본 간격
defaultGap: number; // 8px
// 기본 패딩
defaultPadding: number; // 16px
// 반응형 브레이크포인트 (전역)
breakpoints: {
tablet: number; // 768px
mobile: number; // 480px
};
}
```
---
## 3. 디자이너 UI 변경
### 3.1 기존 디자이너 vs 새 디자이너
```
기존 (그리드 기반):
┌──────────────────────────────────────────────┐
│ [태블릿 가로] [태블릿 세로] [모바일 가로] [모바일 세로] │
│ │
│ 24x24 그리드에 컴포넌트 드래그 배치 │
│ │
└──────────────────────────────────────────────┘
새로운 (제약조건 기반):
┌──────────────────────────────────────────────┐
│ [단일 캔버스] 미리보기: [태블릿▼] │
│ │
│ 스택(컨테이너)에 컴포넌트 배치 │
│ + 우측 패널에서 제약조건 설정 │
│ │
└──────────────────────────────────────────────┘
```
### 3.2 새로운 디자이너 레이아웃
```
┌─────────────────────────────────────────────────────────────────┐
│ POP 화면 디자이너 v4 [저장] [미리보기] │
├────────────────┬────────────────────────┬───────────────────────┤
│ │ │ │
│ 컴포넌트 │ 캔버스 │ 속성 패널 │
│ │ │ │
│ ▼ 기본 │ ┌──────────────────┐ │ ▼ 선택됨: 입력창 │
│ [필드] │ │ ┌──────────────┐ │ │ │
│ [버튼] │ │ │입력창 │ │ │ ▼ 크기 │
│ [리스트] │ │ └──────────────┘ │ │ 너비: [채우기 ▼] │
│ [인디케이터] │ │ │ │ 최소: [100] px │
│ │ │ ┌─────┐ ┌─────┐ │ │ 최대: [없음] │
│ ▼ 입력 │ │ │버튼1│ │버튼2│ │ │ │
│ [스캐너] │ │ └─────┘ └─────┘ │ │ 높이: [고정 ▼] │
│ [숫자패드] │ │ │ │ 값: [48] px │
│ │ └──────────────────┘ │ │
│ ───────── │ │ ▼ 정렬 │
│ │ 미리보기: │ [늘이기 ▼] │
│ ▼ 레이아웃 │ ┌──────────────────┐ │ │
│ [스택 (가로)] │ │[태블릿 가로 ▼] │ │ ▼ 여백 │
│ [스택 (세로)] │ │[768px] │ │ 상[8] 우[0] 하[8] 좌[0]│
│ │ └──────────────────┘ │ │
│ │ │ ▼ 반응형 │
│ │ │ 모바일 스케일: [1.2] │
│ │ │ │
└────────────────┴────────────────────────┴───────────────────────┘
```
### 3.3 컨테이너(스택) 편집
```
┌─ 스택 속성 ─────────────────────┐
│ │
│ 방향: [가로 ▼] │
│ 줄바꿈: [허용 ☑] │
│ 간격: [8] px │
│ │
│ 정렬 (가로): [가운데 ▼] │
│ 정렬 (세로): [늘이기 ▼] │
│ │
│ ▼ 반응형 규칙 │
│ ┌─────────────────────────────┐ │
│ │ 768px 이하: 세로 방향 │ │
│ │ [+ 규칙 추가] │ │
│ └─────────────────────────────┘ │
│ │
└─────────────────────────────────┘
```
---
## 4. 렌더링 로직 변경
### 4.1 기존 렌더링 (CSS Grid)
```typescript
// v3: CSS Grid 기반
<div style={{
display: "grid",
gridTemplateColumns: `repeat(24, 1fr)`,
gridTemplateRows: `repeat(24, 1fr)`,
gap: "4px",
}}>
{componentIds.map(id => (
<div style={{
gridColumn: `${pos.col} / span ${pos.colSpan}`,
gridRow: `${pos.row} / span ${pos.rowSpan}`,
}}>
<Component />
</div>
))}
</div>
```
### 4.2 새로운 렌더링 (Flexbox)
```typescript
// v4: Flexbox 기반
function renderContainer(container: PopContainer, components: Record<string, PopComponentDefinitionV4>) {
const direction = useResponsiveValue(container, 'direction');
const gap = useResponsiveValue(container, 'gap');
return (
<div style={{
display: "flex",
flexDirection: direction === "horizontal" ? "row" : "column",
flexWrap: container.wrap ? "wrap" : "nowrap",
gap: `${gap}px`,
alignItems: container.alignItems,
justifyContent: container.justifyContent,
padding: container.padding ?
`${container.padding.top}px ${container.padding.right}px ${container.padding.bottom}px ${container.padding.left}px`
: undefined,
}}>
{container.children.map(child => {
if (typeof child === "string") {
// 컴포넌트 렌더링
return renderComponent(components[child]);
} else {
// 중첩 컨테이너 렌더링
return renderContainer(child, components);
}
})}
</div>
);
}
function renderComponent(component: PopComponentDefinitionV4) {
const { size, margin, mobileScale } = component;
const isMobile = useIsMobile();
const scale = isMobile && mobileScale ? mobileScale : 1;
// 크기 계산
let width: string;
let flex: string;
if (size.width === "fixed") {
width = `${(size.fixedWidth || 100) * scale}px`;
flex = "0 0 auto";
} else if (size.width === "fill") {
width = "auto";
flex = `${size.flexGrow || 1} ${size.flexShrink || 1} 0`;
} else { // hug
width = "auto";
flex = "0 0 auto";
}
return (
<div style={{
flex,
width,
minWidth: size.minWidth ? `${size.minWidth * scale}px` : undefined,
maxWidth: size.maxWidth ? `${size.maxWidth * scale}px` : undefined,
height: size.height === "fixed" ? `${(size.fixedHeight || 48) * scale}px` : "auto",
minHeight: size.minHeight ? `${size.minHeight * scale}px` : undefined,
maxHeight: size.maxHeight ? `${size.maxHeight * scale}px` : undefined,
margin: margin ?
`${margin.top}px ${margin.right}px ${margin.bottom}px ${margin.left}px`
: undefined,
alignSelf: component.alignSelf,
}}>
<ActualComponent {...component} />
</div>
);
}
```
### 4.3 반응형 훅
```typescript
function useResponsiveValue<T>(
container: PopContainer,
property: keyof PopContainer
): T {
const windowWidth = useWindowWidth();
// 기본값
let value = container[property] as T;
// 반응형 규칙 적용 (작은 브레이크포인트 우선)
if (container.responsive) {
const sortedRules = [...container.responsive].sort((a, b) => b.breakpoint - a.breakpoint);
for (const rule of sortedRules) {
if (windowWidth <= rule.breakpoint && rule[property] !== undefined) {
value = rule[property] as T;
}
}
}
return value;
}
```
---
## 5. 구현 단계
### Phase 1: 데이터 구조 (1-2일)
**파일**: `frontend/components/pop/designer/types/pop-layout.ts`
1. `PopLayoutDataV4` 인터페이스 정의
2. `PopContainer` 인터페이스 정의
3. `PopComponentDefinitionV4` 인터페이스 정의
4. `createEmptyPopLayoutV4()` 함수
5. `migrateV3ToV4()` 마이그레이션 함수
6. `ensureV4Layout()` 함수
7. 타입 가드 함수들
### Phase 2: 렌더러 (2-3일)
**파일**: `frontend/components/pop/designer/renderers/PopLayoutRendererV4.tsx`
1. `renderContainer()` 함수
2. `renderComponent()` 함수
3. `useResponsiveValue()` 훅
4. `useWindowWidth()` 훅
5. CSS 스타일 계산 로직
6. 반응형 브레이크포인트 처리
### Phase 3: 디자이너 UI (3-4일)
**파일**: `frontend/components/pop/designer/PopDesignerV4.tsx`
1. 캔버스 영역 (드래그 앤 드롭)
2. 컴포넌트 팔레트 (기존 + 스택)
3. 속성 패널
- 크기 제약 편집
- 정렬 편집
- 여백 편집
- 반응형 규칙 편집
4. 미리보기 모드 (다양한 화면 크기)
5. 컨테이너(스택) 관리
- 컨테이너 추가/삭제
- 컨테이너 설정 편집
- 컴포넌트 이동 (컨테이너 간)
### Phase 4: 뷰어 통합 (1-2일)
**파일**: `frontend/app/(pop)/pop/screens/[screenId]/page.tsx`
1. v4 레이아웃 감지 및 렌더링
2. 기존 v3 호환 유지
3. 반응형 모드 감지 연동
4. 성능 최적화
### Phase 5: 백엔드 수정 (1일)
**파일**: `backend-node/src/services/screenManagementService.ts`
1. `saveLayoutPop` - v4 버전 감지 및 저장
2. `getLayoutPop` - v4 버전 반환
3. 버전 마이그레이션 로직
### Phase 6: 테스트 및 마이그레이션 (2-3일)
1. 단위 테스트
2. 통합 테스트
3. 기존 v3 레이아웃 마이그레이션 도구
4. 크로스 디바이스 테스트
---
## 6. 마이그레이션 전략
### 6.1 v3 → v4 자동 변환
```typescript
function migrateV3ToV4(v3: PopLayoutDataV3): PopLayoutDataV4 {
// 태블릿 가로 모드 기준으로 변환
const baseLayout = v3.layouts.tablet_landscape;
const componentIds = Object.keys(baseLayout.componentPositions);
// 컴포넌트를 row, col 순으로 정렬
const sortedIds = componentIds.sort((a, b) => {
const posA = baseLayout.componentPositions[a];
const posB = baseLayout.componentPositions[b];
if (posA.row !== posB.row) return posA.row - posB.row;
return posA.col - posB.col;
});
// 같은 row에 있는 컴포넌트들을 가로 스택으로 그룹화
const rowGroups = groupByRow(sortedIds, baseLayout.componentPositions);
// 루트 컨테이너 (세로 스택)
const rootContainer: PopContainer = {
id: "root",
type: "stack",
direction: "vertical",
wrap: false,
gap: v3.settings.canvasGrid.gap,
alignItems: "stretch",
justifyContent: "start",
children: [],
};
// 각 행을 가로 스택으로 변환
for (const [row, ids] of rowGroups) {
if (ids.length === 1) {
// 단일 컴포넌트면 직접 추가
rootContainer.children.push(ids[0]);
} else {
// 여러 컴포넌트면 가로 스택으로 감싸기
const rowStack: PopContainer = {
id: `row-${row}`,
type: "stack",
direction: "horizontal",
wrap: true,
gap: v3.settings.canvasGrid.gap,
alignItems: "center",
justifyContent: "start",
children: ids,
};
rootContainer.children.push(rowStack);
}
}
// 컴포넌트 정의 변환
const components: Record<string, PopComponentDefinitionV4> = {};
for (const id of componentIds) {
const v3Comp = v3.components[id];
const pos = baseLayout.componentPositions[id];
components[id] = {
...v3Comp,
size: {
// colSpan을 기반으로 크기 모드 결정
width: pos.colSpan >= 20 ? "fill" : "fixed",
height: "fixed",
fixedWidth: pos.colSpan * (1024 / 24), // 대략적인 픽셀 변환
fixedHeight: pos.rowSpan * (768 / 24),
minWidth: 100,
},
};
}
return {
version: "pop-4.0",
root: rootContainer,
components,
dataFlow: v3.dataFlow,
settings: {
touchTargetMin: v3.settings.touchTargetMin,
mode: v3.settings.mode,
defaultGap: v3.settings.canvasGrid.gap,
defaultPadding: 16,
breakpoints: {
tablet: 768,
mobile: 480,
},
},
metadata: v3.metadata,
};
}
```
### 6.2 하위 호환
- v3 레이아웃은 계속 지원
- 디자이너에서 v3 → v4 업그레이드 버튼 제공
- 새로 생성하는 레이아웃은 v4
---
## 7. 예상 효과
### 7.1 사용자 경험
| 항목 | 기존 (v3) | 새로운 (v4) |
|------|-----------|-------------|
| 설계 개수 | 4개 | 1개 |
| 작업 시간 | 4배 | 1배 |
| 반응형 | 수동 | 자동 |
| 디바이스 대응 | 각각 설정 | mobileScale |
### 7.2 개발자 경험
| 항목 | 기존 (v3) | 새로운 (v4) |
|------|-----------|-------------|
| 렌더링 | CSS Grid | Flexbox |
| 위치 계산 | col/row | 자동 |
| 반응형 로직 | 4모드 분기 | 브레이크포인트 |
| 유지보수 | 복잡 | 단순 |
---
## 8. 일정 (예상)
| Phase | 내용 | 기간 |
|-------|------|------|
| 1 | 데이터 구조 | 1-2일 |
| 2 | 렌더러 | 2-3일 |
| 3 | 디자이너 UI | 3-4일 |
| 4 | 뷰어 통합 | 1-2일 |
| 5 | 백엔드 수정 | 1일 |
| 6 | 테스트/마이그레이션 | 2-3일 |
| **총계** | | **10-15일** |
---
## 9. 리스크 및 대응
### 9.1 기존 레이아웃 호환성
- **리스크**: v3 → v4 자동 변환이 완벽하지 않을 수 있음
- **대응**:
- 마이그레이션 미리보기 기능
- 수동 조정 도구 제공
- v3 유지 옵션
### 9.2 학습 곡선
- **리스크**: 제약조건 개념이 익숙하지 않을 수 있음
- **대응**:
- 프리셋 제공 (예: "화면 전체 채우기", "고정 크기")
- 툴팁/도움말
- 예제 템플릿
### 9.3 성능
- **리스크**: Flexbox 중첩으로 렌더링 성능 저하
- **대응**:
- 컨테이너 중첩 깊이 제한 (최대 3-4)
- React.memo 활용
- 가상화 (리스트 컴포넌트)
---
## 10. 결론
v4.0 제약조건 기반 시스템은 업계 표준(Figma, Flutter, SwiftUI)을 따르며, 사용자의 작업량을 75% 줄이고 자동 반응형을 제공합니다.
구현 후 POP 디자이너는:
- **1개 레이아웃**만 설계
- **모든 화면 크기**에 자동 적응
- **모바일 특화 설정** (mobileScale)으로 세밀한 제어 가능
---
## 11. 추가 설정 (2026-02-03 업데이트)
### 11.1 확장된 전역 설정
```typescript
interface PopGlobalSettingsV4 {
// 기존
touchTargetMin: number; // 48 (normal) / 60 (industrial)
mode: "normal" | "industrial";
defaultGap: number;
defaultPadding: number;
breakpoints: {
tablet: number; // 768
mobile: number; // 480
};
// 신규 추가
environment: "indoor" | "outdoor"; // 야외면 대비 높임
typography: {
body: { min: number; max: number }; // 14-18px
heading: { min: number; max: number }; // 18-28px
caption: { min: number; max: number }; // 12-14px
};
contrast: "normal" | "high"; // outdoor면 자동 high
}
```
### 11.2 컴포넌트 기본값 프리셋
컴포넌트 추가 시 자동 적용되는 안전한 기본값:
```typescript
const COMPONENT_DEFAULTS = {
"pop-button": {
minWidth: 80,
minHeight: 48,
height: "fixed",
fixedHeight: 48,
},
"pop-field": {
minWidth: 120,
minHeight: 40,
height: "fixed",
fixedHeight: 48,
},
"pop-list": {
minHeight: 200,
itemHeight: 48,
},
// ...
};
```
### 11.3 리스트 반응형 컬럼
```typescript
interface PopListConfig {
// 기존
listType: PopListType;
displayColumns?: string[];
// 신규 추가
responsiveColumns?: {
tablet: string[]; // 전체 컬럼
mobile: string[]; // 주요 컬럼만
};
}
```
### 11.4 라벨 배치 자동화
```typescript
interface PopContainer {
// 기존
direction: "horizontal" | "vertical";
// 신규 추가
labelPlacement?: "auto" | "above" | "beside";
// auto: 모바일 세로=위, 태블릿 가로=옆
}
```
---
## 12. 관련 문서
- [v4 핵심 규칙 가이드](./V4_CORE_RULES.md) - **3가지 핵심 규칙 (필독)**
- [반응형 디자인 가이드](./RESPONSIVE_DESIGN_GUIDE.md)
- [컴포넌트 로드맵](./COMPONENT_ROADMAP.md)
- [크기 프리셋 가이드](./SIZE_PRESETS.md)
- [컴포넌트 상세 스펙](./components-spec.md)
---
## 13. 현재 상태 (2026-02-03)
**구현 대기**: 컴포넌트가 아직 없어서 레이아웃 시스템보다 컴포넌트 개발이 선행되어야 함.
**권장 진행 순서**:
1. 기초 컴포넌트 개발 (PopButton, PopInput 등)
2. 조합 컴포넌트 개발 (PopFormField, PopCard 등)
3. 복합 컴포넌트 개발 (PopDataTable, PopCardList 등)
4. v4 레이아웃 시스템 구현
5. 디자이너 UI 개발
---
*최종 업데이트: 2026-02-03*

0
docs/pop/PROJECT_ARCHITECTURE.md → popdocs/archive/PROJECT_ARCHITECTURE.md
View File

153
popdocs/archive/RESPONSIVE_DESIGN_GUIDE.md Normal file
View File

@ -0,0 +1,153 @@
# POP 반응형 디자인 가이드
## 쉬운 요약
### 핵심 원칙: 3가지만 기억하세요
```
1. 누르는 것 → 크기 고정 (최소 48px)
2. 읽는 것 → 범위 안에서 자동 조절
3. 담는 것 → 화면에 맞춰 늘어남
```
---
## 1. 터치 요소 (고정 크기)
손가락 크기는 화면이 커져도 변하지 않습니다.
| 요소 | 일반 | 산업현장(장갑) |
|------|-----|--------------|
| 버튼 | 48px | 60px |
| 아이콘 (누르는 용) | 48px | 60px |
| 체크박스 | 24px (터치영역 48px) | 24px (터치영역 60px) |
| 리스트 한 줄 높이 | 48px | 56px |
| 입력창 높이 | 40px | 48px |
---
## 2. 텍스트 (범위 조절)
화면 크기에 따라 자동으로 커지거나 작아집니다.
| 용도 | 최소 | 최대 |
|------|-----|-----|
| 본문 | 14px | 18px |
| 제목 | 18px | 28px |
| 설명 | 12px | 14px |
**CSS 예시**:
```css
font-size: clamp(14px, 1.5vw, 18px);
```
---
## 3. 레이아웃 (비율 기반)
컨테이너는 화면에 맞춰 늘어납니다.
| 요소 | 방식 | 예시 |
|------|-----|-----|
| 컨테이너 | 100% | 화면 전체 채움 |
| 카드 2열 | 48% + 48% | 화면 반씩 |
| 입력창 너비 | fill | 부모 채움 |
| 여백 | 8/16/24px | 화면 크기별 |
---
## 4. 환경별 설정
### 일반 (실내)
- 터치: 48px
- 대비: 4.5:1
- 폰트: 14-18px
### 산업현장 (야외/장갑)
- 터치: 60px (+25%)
- 대비: 7:1 이상
- 폰트: 18-22px (+25%)
---
## 5. 리스트/테이블 반응형
화면이 좁아지면 컬럼을 줄입니다.
```
태블릿 (넓음) 모바일 (좁음)
┌──────┬──────┬──────┬──────┐ ┌──────┬──────┐
│품번 │품명 │수량 │상태 │ │품번 │수량 │
├──────┼──────┼──────┼──────┤ ├──────┼──────┤
│A001 │나사 │100 │완료 │ │A001 │100 │
└──────┴──────┴──────┴──────┘ └──────┴──────┘
↳ 터치하면 상세보기
```
---
## 6. 폼 라벨 배치
| 화면 | 라벨 위치 | 이유 |
|------|----------|-----|
| 모바일 세로 | 위 | 입력창 너비 확보 |
| 태블릿 가로 | 옆 | 공간 여유 |
```
모바일 태블릿
┌─────────────────┐ ┌─────────────────────────┐
│ 이름 │ │ 이름: [입력____________] │
│ [입력__________]│ └─────────────────────────┘
└─────────────────┘
```
---
## 7. 그림으로 보는 반응형
```
8인치 태블릿 12인치 태블릿
┌─────────────────┐ ┌───────────────────────┐
│ [버튼 48px] │ │ [버튼 48px] │ ← 버튼 크기 동일!
│ │ │ │
│ ┌─────────────┐ │ │ ┌─────────────────┐ │
│ │ 입력창 │ │ │ │ 입력창 │ │ ← 너비만 늘어남
│ └─────────────┘ │ │ └─────────────────┘ │
│ │ │ │
│ 글자 14px │ │ 글자 18px │ ← 글자만 커짐
└─────────────────┘ └───────────────────────┘
```
---
## 8. 색상 대비 (야외용)
| 환경 | 최소 대비 | 권장 |
|------|----------|-----|
| 실내 | 4.5:1 | 7:1 |
| 야외 | 7:1 | 10:1+ |
**좋은 조합**:
- 흰 배경 + 검정 글자
- 검정 배경 + 흰 글자
- 노랑 경고 + 검정 글자
**피해야 할 조합**:
- 연한 회색 + 밝은 회색
- 빨강 + 녹색 (색맹 고려)
---
## 체크리스트
### 컴포넌트 만들 때 확인
- [ ] 버튼/터치 요소 최소 48px인가?
- [ ] 폰트에 clamp() 적용했나?
- [ ] 색상 대비 4.5:1 이상인가?
- [ ] 모바일에서 라벨이 위에 있나?
- [ ] 리스트가 좁은 화면에서 컬럼 줄어드나?
---
*최종 업데이트: 2026-02-03*

205
popdocs/archive/SIZE_PRESETS.md Normal file
View File

@ -0,0 +1,205 @@
# POP 크기 프리셋 가이드
## 컴포넌트별 기본 크기
컴포넌트를 만들면 자동으로 적용되는 크기입니다.
---
## 버튼 (PopButton)
| 사이즈 | 높이 | 최소 너비 | 폰트 | 용도 |
|-------|------|----------|------|-----|
| sm | 32px | 60px | 12px | 보조 버튼 |
| md | 40px | 80px | 14px | 일반 버튼 |
| **lg** | **48px** | **100px** | **16px** | **POP 기본** |
| xl | 56px | 120px | 18px | 주요 액션 |
| industrial | 60px | 140px | 20px | 장갑 착용 |
```typescript
// POP에서는 lg가 기본
<PopButton size="lg">확인</PopButton>
// 산업현장
<PopButton size="industrial">작업 완료</PopButton>
```
---
## 입력창 (PopInput)
| 사이즈 | 높이 | 폰트 | 용도 |
|-------|------|------|-----|
| md | 40px | 14px | 일반 |
| **lg** | **48px** | **16px** | **POP 기본** |
| xl | 56px | 18px | 강조 입력 |
```typescript
// 입력창 너비는 항상 부모 채움 (fill)
<PopInput size="lg" />
```
---
## 리스트 행 (PopListItem)
| 사이즈 | 높이 | 폰트 | 용도 |
|-------|------|------|-----|
| compact | 40px | 14px | 많은 데이터 |
| **normal** | **48px** | **16px** | **POP 기본** |
| spacious | 56px | 18px | 여유로운 |
| industrial | 64px | 20px | 장갑 착용 |
```typescript
<PopListItem size="normal">
<span>작업지시 #1234</span>
</PopListItem>
```
---
## 아이콘 (PopIcon)
| 사이즈 | 크기 | 터치 영역 | 용도 |
|-------|-----|----------|-----|
| sm | 16px | 32px | 뱃지 안 |
| md | 20px | 40px | 텍스트 옆 |
| **lg** | **24px** | **48px** | **POP 기본** |
| xl | 32px | 56px | 강조 |
```typescript
// 아이콘만 있는 버튼
<PopButton icon="check" size="lg" />
// 텍스트 + 아이콘
<PopButton icon="save" size="lg">저장</PopButton>
```
---
## 카드 (PopCard)
| 요소 | 크기 |
|------|-----|
| 패딩 | 16px |
| 제목 폰트 | 18px (heading) |
| 본문 폰트 | 16px (body) |
| 모서리 | 8px |
| 최소 높이 | 100px |
```typescript
<PopCard>
<PopCard.Header>작업지시</PopCard.Header>
<PopCard.Body>내용</PopCard.Body>
</PopCard>
```
---
## 숫자패드 (PopNumberPad)
| 요소 | 크기 |
|------|-----|
| 버튼 크기 | 60px x 60px |
| 버튼 간격 | 8px |
| 전체 너비 | 240px |
| 폰트 | 24px |
```
┌─────────────────────┐
│ [ 123 ] │ ← 디스플레이 48px
├─────┬─────┬─────────┤
│ 7 │ 8 │ 9 │ ← │ ← 각 버튼 60x60
├─────┼─────┼─────────┤
│ 4 │ 5 │ 6 │ C │
├─────┼─────┼─────────┤
│ 1 │ 2 │ 3 │ │
├─────┼─────┼─────│ OK│
│ 0 │ . │ +- │ │
└─────┴─────┴─────────┘
```
---
## 상태 표시 (PopStatusBox)
| 사이즈 | 너비 | 높이 | 아이콘 | 용도 |
|-------|-----|------|-------|-----|
| sm | 80px | 60px | 24px | 여러 개 나열 |
| **md** | **120px** | **80px** | **32px** | **POP 기본** |
| lg | 160px | 100px | 40px | 강조 |
```typescript
<PopStatusBox
label="설비 상태"
value="가동중"
status="success"
size="md"
/>
```
---
## KPI 게이지 (PopKpiGauge)
| 사이즈 | 너비 | 높이 | 용도 |
|-------|-----|------|-----|
| sm | 120px | 120px | 여러 개 나열 |
| **md** | **180px** | **180px** | **POP 기본** |
| lg | 240px | 240px | 강조 |
---
## 간격 (Gap/Padding)
| 이름 | 값 | 용도 |
|------|---|-----|
| xs | 4px | 아이콘-텍스트 |
| sm | 8px | 요소 내부 |
| **md** | **16px** | **컴포넌트 간** |
| lg | 24px | 섹션 간 |
| xl | 32px | 영역 구분 |
---
## 반응형 조절
화면 크기에 따라 자동 조절되는 값들:
| 요소 | 8인치 태블릿 | 12인치 태블릿 |
|------|------------|--------------|
| 본문 폰트 | 14px | 18px |
| 제목 폰트 | 18px | 28px |
| 컨테이너 패딩 | 12px | 24px |
| 카드 간격 | 12px | 16px |
**고정되는 값들 (변하지 않음)**:
- 버튼 높이: 48px
- 입력창 높이: 48px
- 리스트 행 높이: 48px
- 터치 최소 영역: 48px
---
## 적용 예시
```typescript
// 컴포넌트 내부에서 자동 적용
function PopButton({ size = "lg", ...props }) {
const sizeStyles = {
sm: { height: 32, minWidth: 60, fontSize: 12 },
md: { height: 40, minWidth: 80, fontSize: 14 },
lg: { height: 48, minWidth: 100, fontSize: 16 }, // POP 기본
xl: { height: 56, minWidth: 120, fontSize: 18 },
industrial: { height: 60, minWidth: 140, fontSize: 20 },
};
return (
<button style={sizeStyles[size]} {...props} />
);
}
```
---
*최종 업데이트: 2026-02-03*

240
popdocs/archive/V4_CORE_RULES.md Normal file
View File

@ -0,0 +1,240 @@
# POP v4 핵심 규칙 가이드
## 개요
v4에서는 **"위치"를 설정하는 게 아니라 "규칙"을 설정**합니다.
```
v3 (기존): 4개 모드 각각 컴포넌트 위치 설정 → 4배 작업량
v4 (신규): 3가지 규칙만 설정 → 모든 화면 자동 적응
```
---
## 핵심 규칙 3가지
### 1. 크기 규칙 (Size Rules)
각 컴포넌트의 **너비**와 **높이**를 어떻게 결정할지 정합니다.
| 모드 | 설명 | 예시 |
|------|------|------|
| **fixed** | 고정 px | 버튼 높이 48px |
| **fill** | 부모 공간 채움 | 입력창 너비 = 화면 너비 |
| **hug** | 내용에 맞춤 | 라벨 너비 = 텍스트 길이 |
```typescript
// 예시: 버튼
{
width: "fill", // 화면 너비에 맞춤
height: "fixed", // 고정
fixedHeight: 48 // 48px
}
// 예시: 라벨
{
width: "hug", // 텍스트 길이만큼
height: "hug" // 텍스트 높이만큼
}
```
#### 크기 모드 시각화
```
fixed (고정):
├────48px────┤
┌────────────┐
│ 버튼 │ ← 화면 커져도 48px 유지
└────────────┘
fill (채움):
├─────────────────────────────────┤
┌─────────────────────────────────┐
│ 입력창 │ ← 화면 크기에 맞춤
└─────────────────────────────────┘
hug (맞춤):
├──────┤
┌──────┐
│라벨 │ ← 내용 길이만큼만
└──────┘
```
---
### 2. 배치 규칙 (Layout Rules)
컴포넌트들을 **어떻게 나열할지** 정합니다.
#### 스택 방향
```
가로 스택 (horizontal): 세로 스택 (vertical):
┌─────┬─────┬─────┐ ┌─────────────┐
│ A │ B │ C │ │ A │
└─────┴─────┴─────┘ ├─────────────┤
│ B │
├─────────────┤
│ C │
└─────────────┘
```
#### 설정 항목
| 항목 | 설명 | 옵션 |
|------|------|------|
| **direction** | 스택 방향 | horizontal / vertical |
| **wrap** | 줄바꿈 허용 | true / false |
| **gap** | 요소 간 간격 | 8 / 16 / 24 px |
| **alignItems** | 교차축 정렬 | start / center / end / stretch |
| **justifyContent** | 주축 정렬 | start / center / end / space-between |
```typescript
// 예시: 버튼 그룹 (가로 배치)
{
direction: "horizontal",
wrap: true, // 공간 부족하면 줄바꿈
gap: 16, // 버튼 간격 16px
alignItems: "center" // 세로 중앙 정렬
}
```
---
### 3. 반응형 규칙 (Responsive Rules)
**화면이 좁아지면** 어떻게 바꿀지 정합니다.
```typescript
// 예시: 768px 이하면 가로→세로 전환
{
direction: "horizontal",
responsive: [
{
breakpoint: 768, // 768px 이하일 때
direction: "vertical" // 세로로 바꿈
}
]
}
```
#### 시각화
```
768px 이상 (태블릿): 768px 이하 (모바일):
┌─────┬─────┬─────┐ ┌─────────────┐
│ A │ B │ C │ → │ A │
└─────┴─────┴─────┘ │ B │
│ C │
└─────────────┘
```
---
## 실제 예시: 작업지시 화면
### 규칙 설정
```typescript
{
root: {
type: "stack",
direction: "vertical",
gap: 16,
padding: { top: 16, right: 16, bottom: 16, left: 16 },
children: ["header", "form", "buttons"]
},
containers: {
"header": {
type: "stack",
direction: "horizontal",
alignItems: "center",
children: ["title", "status"]
},
"form": {
type: "stack",
direction: "vertical",
gap: 12,
children: ["field1", "field2", "field3"]
},
"buttons": {
type: "stack",
direction: "horizontal",
gap: 12,
responsive: [
{ breakpoint: 480, direction: "vertical" }
],
children: ["cancelBtn", "submitBtn"]
}
},
components: {
"title": { width: "hug", height: "hug" },
"status": { width: "hug", height: "hug" },
"field1": { width: "fill", height: "fixed", fixedHeight: 48 },
"field2": { width: "fill", height: "fixed", fixedHeight: 48 },
"field3": { width: "fill", height: "fixed", fixedHeight: 48 },
"cancelBtn": { width: "fill", height: "fixed", fixedHeight: 48 },
"submitBtn": { width: "fill", height: "fixed", fixedHeight: 48 }
}
}
```
### 결과
```
태블릿 가로 (1024px) 모바일 세로 (375px)
┌──────────────────────────┐ ┌─────────────────┐
│ 작업지시 #1234 [진행중]│ │작업지시 [진행]│
├──────────────────────────┤ ├─────────────────┤
│ [품번____________] │ │[품번_________] │
│ [품명____________] │ │[품명_________] │
│ [수량____________] │ │[수량_________] │
├──────────────────────────┤ ├─────────────────┤
│ [취소] [작업완료] │ │[취소] │
└──────────────────────────┘ │[작업완료] │
└─────────────────┘
```
---
## v3 vs v4 비교
| 항목 | v3 (기존) | v4 (신규) |
|------|----------|----------|
| **설계 방식** | 4개 모드 각각 위치 설정 | 3가지 규칙 설정 |
| **작업량** | 4배 | 1배 |
| **데이터** | col, row, colSpan, rowSpan | width, height, direction, gap |
| **반응형** | 수동 (모드별 설정) | 자동 (브레이크포인트) |
| **유지보수** | 4곳 수정 | 1곳 수정 |
---
## 규칙 설계 체크리스트
### 크기 규칙
- [ ] 터치 요소(버튼, 입력창) 높이: fixed 48px
- [ ] 너비가 화면에 맞아야 하는 요소: fill
- [ ] 내용 길이에 맞아야 하는 요소: hug
### 배치 규칙
- [ ] 컴포넌트 나열 방향 결정 (가로/세로)
- [ ] 간격 설정 (8/16/24px)
- [ ] 정렬 방식 결정 (start/center/stretch)
### 반응형 규칙
- [ ] 768px 이하에서 가로→세로 전환 필요한 곳
- [ ] 480px 이하에서 추가 조정 필요한 곳
---
## 관련 문서
- [반응형 디자인 가이드](./RESPONSIVE_DESIGN_GUIDE.md) - 크기 기준
- [크기 프리셋](./SIZE_PRESETS.md) - 컴포넌트별 기본값
- [v4 구현 계획](./POP_V4_CONSTRAINT_SYSTEM_PLAN.md) - 전체 계획
---
*최종 업데이트: 2026-02-04*

0
docs/pop/components-spec.md → popdocs/components-spec.md
View File

119
popdocs/decisions/001-v4-constraint-based.md Normal file
View File

@ -0,0 +1,119 @@
# ADR-001: v4 제약조건 기반 레이아웃 채택
**날짜**: 2026-02-03
**상태**: 채택됨
**의사결정자**: 프로젝트 담당자
---
## 배경
v3에서는 4개 모드(tablet_landscape, tablet_portrait, mobile_landscape, mobile_portrait)에 대해 각각 컴포넌트 위치를 설정해야 했습니다.
**문제점**:
1. 같은 컴포넌트를 4번 배치해야 함 (4배 작업량)
2. 모드 간 일관성 유지 어려움
3. 새 모드 추가 시 또 다른 배치 필요
---
## 결정
**"단일 소스 + 자동 적응" 방식 채택**
Figma, Framer, Flutter, SwiftUI에서 사용하는 업계 표준 접근법:
- 하나의 레이아웃 정의
- 제약조건(constraints) 설정
- 모든 화면에 자동 적응
---
## 핵심 규칙 3가지
### 1. 크기 규칙 (Size Rules)
| 모드 | 설명 | 예시 |
|------|------|------|
| fixed | 고정 px | 버튼 높이 48px |
| fill | 부모 채움 | 입력창 100% |
| hug | 내용 맞춤 | 라벨 = 텍스트 길이 |
### 2. 배치 규칙 (Layout Rules)
- 스택 방향: horizontal / vertical
- 줄바꿈: wrap / nowrap
- 간격: gap (8/16/24px)
- 정렬: start / center / end / stretch
### 3. 반응형 규칙 (Responsive Rules)
```typescript
{
direction: "horizontal",
responsive: [
{ breakpoint: 768, direction: "vertical" }
]
}
```
---
## 구현 방식
**Flexbox 기반** (CSS Grid 아님)
이유:
- 1차원 배치에 최적화
- 자동 크기 계산 (hug)
- 반응형 전환 간단
---
## 대안 검토
### A. 기존 4모드 유지 (기각)
장점: 기존 코드 변경 없음
단점: 근본 문제 해결 안 됨
### B. CSS Grid 기반 (기각)
장점: 2차원 배치 가능
단점: hug 구현 복잡, 학습 곡선
### C. 제약조건 기반 (채택)
장점: 업계 표준, 1회 설계
단점: 기존 v3와 호환성 고려 필요
---
## 영향
### 변경 필요
- 타입 정의 (PopLayoutDataV4)
- 렌더러 (Flexbox 기반)
- 디자이너 UI (제약조건 편집)
### 호환성
- v3 레이아웃은 기존 방식으로 계속 작동
- v4는 새로운 레이아웃에만 적용
- 점진적 마이그레이션 가능
---
## 참조
- Figma Auto Layout: https://help.figma.com/hc/en-us/articles/5731482952599-Using-auto-layout
- Flutter Flex: https://docs.flutter.dev/development/ui/layout
- SwiftUI Stacks: https://developer.apple.com/documentation/swiftui/hstack
---
## 관련
- rangraph 검색: "v4 constraint", "layout system"
- SPEC.md: 상세 규칙
- PLAN.md: 구현 로드맵