combat-ui-pattern-a

# Combat UI Pattern A - Split-Panel Implementation

This skill guides implementation of the Split-Panel Combat UI, transforming the vertical theater mode into a horizontal confrontation layout.

## Architecture Overview

```
┌───────────────────────────────────────────────────┐
│  TURN INDICATOR  │  PHASE PIPELINE  │  MODIFIERS  │  ← PhaseHeader
├──────────────────┴───────┬───────────┴────────────┤
│                          │                        │
│     PLAYER PANEL         │     ENEMY PANEL        │  ← ConfrontationZone
│     (CharacterPanel)     │     (CharacterPanel)   │
│                          │                        │
├──────────────────────────┴────────────────────────┤
│  QUICK ACTIONS (SIDE/TOGGLE)  │   MAIN ACTIONS    │  ← ActionDock
└───────────────────────────────┴───────────────────┘
```

## Component Hierarchy

```
Combat.tsx (scene orchestrator)
├── CombatLayout.tsx (CSS Grid container)
│   ├── PhaseHeader.tsx (top status bar)
│   │   ├── TurnIndicator
│   │   ├── PhasePipeline
│   │   ├── SideActionCounter
│   │   └── ApproachModifier
│   │
│   ├── ConfrontationZone.tsx (battle area)
│   │   ├── CharacterPanel.tsx (player variant)
│   │   │   ├── CharacterSprite
│   │   │   ├── IdentityBar
│   │   │   ├── ResourceBars (HP/CP)
│   │   │   └── BuffBar
│   │   │
│   │   ├── VSDivider.tsx (center emblem)
│   │   │
│   │   └── CharacterPanel.tsx (enemy variant)
│   │       ├── CharacterSprite
│   │       ├── IdentityBar (name, tier, element)
│   │       ├── HealthBar
│   │       ├── DefenseStats
│   │       └── BuffBar
│   │
│   └── ActionDock.tsx (skill bar)
│       ├── QuickActionsSection
│       │   ├── QuickActionCard (SIDE skills)
│       │   └── QuickActionCard (TOGGLE skills)
│       ├── MainActionsSection
│       │   └── MainActionCard (MAIN skills)
│       └── ControlButtons (Auto, End Turn)
│
└── FloatingTextLayer (z-50, unchanged)
```

## File Structure

```
src/components/combat/
├── index.ts                  # Barrel exports
├── CombatLayout.tsx          # Grid container
├── PhaseHeader.tsx           # Top status bar
├── ConfrontationZone.tsx     # Player vs Enemy area
├── CharacterPanel.tsx        # Reusable character display
├── VSDivider.tsx             # Center VS emblem
├── ActionDock.tsx            # Bottom skill bar
├── QuickActionCard.tsx       # Compact SIDE/TOGGLE card
└── MainActionCard.tsx        # Large MAIN skill card
```

## Implementation Workflow

### Step 1: Identify Target Component

Ask user which component to implement:

1. **CombatLayout** - Start here for new implementation
2. **PhaseHeader** - Top status bar
3. **ConfrontationZone** - Battle area with both panels
4. **CharacterPanel** - Individual character display
5. **VSDivider** - Center emblem and effects
6. **ActionDock** - Bottom skill bar
7. **QuickActionCard** - Compact skill card variant
8. **MainActionCard** - Large skill card variant

### Step 2: Load Component Reference

Based on selection, load the appropriate reference:

- **Layout/Structure**: See [layout-specs.md](references/layout-specs.md)
- **Component Props**: See [component-interfaces.md](references/component-interfaces.md)
- **Styling Guide**: See [styling-tokens.md](references/styling-tokens.md)
- **Animation Specs**: See [animations.md](references/animations.md)

### Step 3: Generate Component Code

Follow the component template pattern:

```typescript
import React from 'react';
import { cn } from '@/lib/utils'; // if using cn utility

interface ComponentNameProps {
  // Props from component-interfaces.md
}

export const ComponentName: React.FC<ComponentNameProps> = ({
  // destructured props
}) => {
  return (
    <div className={cn(
      // Base styles from styling-tokens.md
      // Conditional styles
    )}>
      {/* Component content */}
    </div>
  );
};
```

### Step 4: Wire to Combat.tsx

After component creation:

1. Export from `components/combat/index.ts`
2. Import in `Combat.tsx`
3. Replace corresponding section
4. Pass required props from existing state

## Quick Implementation Commands

### Create All Files (Scaffolding)

```bash
# Create directory
mkdir -p src/components/combat

# Create all component files
touch src/components/combat/{index,CombatLayout,PhaseHeader,ConfrontationZone,CharacterPanel,VSDivider,ActionDock,QuickActionCard,MainActionCard}.tsx
```

### Barrel Export Template

```typescript
// 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 Mapping from Existing Code

### From App.tsx → Combat.tsx (unchanged)

```typescript
player: Player
enemy: Enemy
turnState: 'PLAYER' | 'ENEMY_TURN'
turnPhase: TurnPhaseState
combatState: CombatState
onUseSkill: (skill: Skill) => void
onPassTurn: () => void
onToggleAutoCombat: () => void
autoCombatEnabled: boolean
```

### Combat.tsx → New Components

```typescript
// PhaseHeader
turnState, turnPhase, combatState.approach

// ConfrontationZone
player, enemy, playerStats, enemyStats

// CharacterPanel (player)
character: player, stats: playerStats, variant: 'player'

// CharacterPanel (enemy)
character: enemy, stats: enemyStats, variant: 'enemy'

// ActionDock
skills: player.skills, turnPhase, onUseSkill, onPassTurn
```

## Migration Strategy

### Phase 1: Layout Foundation
1. Create `CombatLayout.tsx` with CSS Grid
2. Create placeholder components
3. Add feature flag in Combat.tsx

### Phase 2: Component Extraction
4. Implement `CharacterPanel` (extract from PlayerHUD + CinematicViewscreen)
5. Implement `ActionDock` (extract from skill grids)
6. Implement `PhaseHeader` (extract from inline indicators)

### Phase 3: Visual Polish
7. Add `VSDivider` with effects
8. Implement animations
9. Adjust floating text positions

### Phase 4: Cleanup
10. Remove old theater mode code
11. Remove feature flag
12. Update tests

## Reference Files

- [layout-specs.md](references/layout-specs.md) - CSS Grid structure, responsive breakpoints
- [component-interfaces.md](references/component-interfaces.md) - TypeScript interfaces for all components
- [styling-tokens.md](references/styling-tokens.md) - Colors, spacing, typography tokens
- [animations.md](references/animations.md) - Animation keyframes and transitions

## Output Format

Generate TypeScript React components with:

1. **TypeScript interface** for props
2. **Tailwind CSS** for styling (matching existing codebase)
3. **Responsive classes** (mobile fallback to vertical)
4. **Memoization** where appropriate (React.memo for cards)
5. **Accessibility** attributes (aria-labels, roles)

## Existing Code References

When implementing, reference these existing files:

| New Component | Reference From |
|---------------|----------------|
| CharacterPanel (player) | `src/components/PlayerHUD.tsx` |
| CharacterPanel (enemy) | `src/scenes/Combat.tsx` lines 113-305 |
| ActionDock | `src/scenes/Combat.tsx` lines 308-607 |
| QuickActionCard | `src/components/SkillCard.tsx` |
| MainActionCard | `src/components/SkillCard.tsx` |
| PhaseHeader | `src/scenes/Combat.tsx` lines 311-328 |