전투 UI 패턴 A - 분할 패널 구현
이 스킬은 분할 패널 전투 UI를 구현하여 세로 극장 모드를 가로 대치 레이아웃으로 변환합니다.
아키텍처 개요
┌───────────────────────────────────────────────────┐
│ 턴 표시기 │ 페이즈 파이프라인 │ 수정자 │ ← PhaseHeader
├──────────────────┴───────┬───────────┴────────────┤
│ │ │
│ 플레이어 패널 │ 적 패널 │ ← ConfrontationZone
│ (CharacterPanel) │ (CharacterPanel) │
│ │ │
├──────────────────────────┴────────────────────────┤
│ 빠른 행동 (사이드/토글) │ 주요 행동 │ ← ActionDock
└───────────────────────────────┴───────────────────┘
컴포넌트 계층 구조
Combat.tsx (씬 오케스트레이터)
├── CombatLayout.tsx (CSS 그리드 컨테이너)
│ ├── PhaseHeader.tsx (상단 상태 표시줄)
│ │ ├── TurnIndicator
│ │ ├── PhasePipeline
│ │ ├── SideActionCounter
│ │ └── ApproachModifier
│ │
│ ├── ConfrontationZone.tsx (전투 영역)
│ │ ├── CharacterPanel.tsx (플레이어 변형)
│ │ │ ├── CharacterSprite
│ │ │ ├── IdentityBar
│ │ │ ├── ResourceBars (HP/CP)
│ │ │ └── BuffBar
│ │ │
│ │ ├── VSDivider.tsx (중앙 엠블럼)
│ │ │
│ │ └── CharacterPanel.tsx (적 변형)
│ │ ├── CharacterSprite
│ │ ├── IdentityBar (이름, 등급, 속성)
│ │ ├── HealthBar
│ │ ├── DefenseStats
│ │ └── BuffBar
│ │
│ └── ActionDock.tsx (스킬 바)
│ ├── QuickActionsSection
│ │ ├── QuickActionCard (사이드 스킬)
│ │ └── QuickActionCard (토글 스킬)
│ ├── MainActionsSection
│ │ └── MainActionCard (메인 스킬)
│ └── ControlButtons (자동, 턴 종료)
│
└── FloatingTextLayer (z-50, 변경 없음)
파일 구조
src/components/combat/
├── index.ts # 배럴 익스포트
├── CombatLayout.tsx # 그리드 컨테이너
├── PhaseHeader.tsx # 상단 상태 표시줄
├── ConfrontationZone.tsx # 플레이어 vs 적 영역
├── CharacterPanel.tsx # 재사용 가능한 캐릭터 표시
├── VSDivider.tsx # 중앙 VS 엠블럼
├── ActionDock.tsx # 하단 스킬 바
├── QuickActionCard.tsx # 컴팩트 사이드/토글 카드
└── MainActionCard.tsx # 큰 메인 스킬 카드
구현 워크플로우
1단계: 대상 컴포넌트 식별
사용자에게 구현할 컴포넌트를 질문합니다:
- CombatLayout - 새 구현은 여기서 시작
- PhaseHeader - 상단 상태 표시줄
- ConfrontationZone - 양쪽 패널이 있는 전투 영역
- CharacterPanel - 개별 캐릭터 표시
- VSDivider - 중앙 엠블럼 및 효과
- ActionDock - 하단 스킬 바
- QuickActionCard - 컴팩트 스킬 카드 변형
- MainActionCard - 큰 스킬 카드 변형
2단계: 컴포넌트 레퍼런스 로드
선택에 따라 적절한 레퍼런스를 로드합니다:
- 레이아웃/구조: layout-specs.md 참조
- 컴포넌트 Props: component-interfaces.md 참조
- 스타일링 가이드: styling-tokens.md 참조
- 애니메이션 명세: animations.md 참조
3단계: 컴포넌트 코드 생성
컴포넌트 템플릿 패턴을 따릅니다:
import React from 'react';
import { cn } from '@/lib/utils'; // cn 유틸리티를 사용하는 경우
interface ComponentNameProps {
// component-interfaces.md의 Props
}
export const ComponentName: React.FC<ComponentNameProps> = ({
// 구조 분해된 props
}) => {
return (
<div className={cn(
// styling-tokens.md의 기본 스타일
// 조건부 스타일
)}>
{/* 컴포넌트 내용 */}
</div>
);
};
4단계: Combat.tsx에 연결
컴포넌트 생성 후:
components/combat/index.ts에서 내보내기Combat.tsx에서 가져오기- 해당 섹션 교체
- 기존 상태에서 필요한 props 전달
빠른 구현 명령어
모든 파일 생성 (스캐폴딩)
# 디렉토리 생성
mkdir -p src/components/combat
# 모든 컴포넌트 파일 생성
touch src/components/combat/{index,CombatLayout,PhaseHeader,ConfrontationZone,CharacterPanel,VSDivider,ActionDock,QuickActionCard,MainActionCard}.tsx
배럴 익스포트 템플릿
// src/components/combat/index.ts
export { CombatLayout } from './CombatLayout';
export { PhaseHeader } from './PhaseHeader';
export { ConfrontationZone } from './ConfrontationZone';
export { CharacterPanel } from './CharacterPanel';
export { VSDivider } from './VSDivider';
export { ActionDock } from './ActionDock';
export { QuickActionCard } from './QuickActionCard';
export { MainActionCard } from './MainActionCard';
기존 코드에서의 Props 매핑
App.tsx → Combat.tsx (변경 없음)
player: Player
enemy: Enemy
turnState: 'PLAYER' | 'ENEMY_TURN'
turnPhase: TurnPhaseState
combatState: CombatState
onUseSkill: (skill: Skill) => void
onPassTurn: () => void
onToggleAutoCombat: () => void
autoCombatEnabled: boolean
Combat.tsx → 새 컴포넌트
// PhaseHeader
turnState, turnPhase, combatState.approach
// ConfrontationZone
player, enemy, playerStats, enemyStats
// CharacterPanel (플레이어)
character: player, stats: playerStats, variant: 'player'
// CharacterPanel (적)
character: enemy, stats: enemyStats, variant: 'enemy'
// ActionDock
skills: player.skills, turnPhase, onUseSkill, onPassTurn
마이그레이션 전략
1단계: 레이아웃 기반
- CSS 그리드로
CombatLayout.tsx생성 - 플레이스홀더 컴포넌트 생성
- Combat.tsx에 기능 플래그 추가
2단계: 컴포넌트 추출
CharacterPanel구현 (PlayerHUD + CinematicViewscreen에서 추출)ActionDock구현 (스킬 그리드에서 추출)PhaseHeader구현 (인라인 표시기에서 추출)
3단계: 시각적 개선
- 효과가 있는
VSDivider추가 - 애니메이션 구현
- 플로팅 텍스트 위치 조정
4단계: 정리
- 이전 극장 모드 코드 제거
- 기능 플래그 제거
- 테스트 업데이트
레퍼런스 파일
- layout-specs.md - CSS 그리드 구조, 반응형 중단점
- component-interfaces.md - 모든 컴포넌트의 TypeScript 인터페이스
- styling-tokens.md - 색상, 간격, 타이포그래피 토큰
- animations.md - 애니메이션 키프레임 및 전환
출력 형식
다음과 같은 TypeScript React 컴포넌트를 생성합니다:
- TypeScript 인터페이스 (props용)
- Tailwind CSS (스타일링, 기존 코드베이스와 일치)
- 반응형 클래스 (모바일은 세로로 폴백)
- 메모이제이션 (카드에는 React.memo 사용)
- 접근성 속성 (aria-labels, roles)
기존 코드 레퍼런스
구현 시 다음 기존 파일을 참조합니다:
| 새 컴포넌트 | 레퍼런스 출처 |
|---|---|
| CharacterPanel (플레이어) | src/components/PlayerHUD.tsx |
| CharacterPanel (적) | src/scenes/Combat.tsx 113-305행 |
| ActionDock | src/scenes/Combat.tsx 308-607행 |
| QuickActionCard | src/components/SkillCard.tsx |
| MainActionCard | src/components/SkillCard.tsx |
| PhaseHeader | src/scenes/Combat.tsx 311-328행 |