feat: implement Phase 30 - useGameStatus hook

Extract game status logic into dedicated hook following vim-maze pattern:

New Module Structure:
- src/useGameStatus/types.ts: GameStatus and GameStatusManager types
- src/useGameStatus/useGameStatus.ts: Hook implementation
- src/useGameStatus/index.ts: Public exports

Hook Implementation:
- State machine with 5 states (waiting/started/paused/game-over/game-won)
- Methods: startGame, togglePause, quitGame, setGameStatus
- Clean state transitions with useState
- Simpler than vim-maze (no intermediate 'has-key' state)

Updated Core Files:
- src/useGame.ts: Use useGameStatus() instead of inline useState
  - Compose gameStatusManager into GameManager
  - Cleaner separation of concerns

- src/types.ts: Import and re-export GameStatus types
  - GameManager extends GameStatusManager (intersection type)
  - Single source of truth for status types

- src/index.ts: Export useGameStatus hook publicly

Benefits:
- Reusable state machine
- Easier to test in isolation
- Follows unified API architecture
- Matches vim-maze patterns

State Transitions:
waiting → startGame() → started ↔ togglePause() ↔ paused
started → (win/lose) → game-won/game-over
* → quitGame() → waiting

Phase 30 complete. Next: Phase 40 (useCursor composition).
This commit is contained in:
2025-10-22 18:45:56 +01:00
parent 6f4a1accc4
commit 4e14d54122
8 changed files with 163 additions and 28 deletions
+107 -1
View File
@@ -314,6 +314,112 @@ pattern(r, c) = (3 * (r % 3) + floor(r / 3) + c) % 9 + 1
---
## Iteration 5: [Pending]
## Iteration 5: Phase 30 - useGameStatus Hook
**Date**: 2025-01-22
### Goals
- Extract game status logic into dedicated hook
- Follow vim-maze architecture pattern
- Clean separation of concerns
- Reusable state machine
### Tasks Completed
#### 1. Created useGameStatus Module
**File Structure**:
```
src/useGameStatus/
├── index.ts # Public exports
├── types.ts # GameStatus, GameStatusManager
└── useGameStatus.ts # Hook implementation
```
#### 2. Implemented State Machine
**States**:
- `waiting` - Initial state, awaiting start
- `started` - Game in progress
- `paused` - Game temporarily paused
- `game-over` - Game lost
- `game-won` - Game completed
**State Transitions**:
```
waiting ──startGame()──> started
▲ │
│ │ togglePause()
│ ▼
quitGame() paused
│
│ togglePause()
▼
started
```
#### 3. Hook API
```typescript
const gameStatusManager = useGameStatus();
const {
gameStatus, // Current state
setGameStatus, // Direct setter (for special cases)
startGame, // waiting → started
togglePause, // started ↔ paused
quitGame, // * → waiting
} = gameStatusManager;
```
#### 4. Updated useGame
- Removed inline `useState<GameStatus>`
- Uses `useGameStatus()` hook
- Spreads `gameStatusManager` into `GameManager`
- Cleaner, more maintainable code
#### 5. Updated Type System
**types.ts**:
- Imports `GameStatus` and `GameStatusManager` from useGameStatus
- Re-exports for public API
- `GameManager` extends `GameStatusManager` (intersection type)
- Avoids duplication, single source of truth
### Technical Details
**Simpler than vim-maze**:
- No intermediate states (no 'has-key' equivalent)
- Straightforward: waiting → started → won/over
- Pause is optional toggle, not a separate flow
**Hook Composition**:
```typescript
// In useGame
const gameStatusManager = useGameStatus();
const { gameStatus } = gameStatusManager;
// Compose into GameManager
const gameManager = {
...gameStatusManager, // gameStatus, startGame, etc.
// ... other managers
};
```
**Type Safety**:
- `GameManager` extends `GameStatusManager`
- All status methods available on gameManager
- Full TypeScript inference throughout
### Build Status
- ✅ TypeScript compiles cleanly
- ✅ Example app builds successfully
- ✅ No breaking changes to public API
### Next Steps
- Phase 40: useCursor Hook Composition
- useCellEditor (analog to useHero)
- useVimMotions
- useGameKeys
- useCursorRender
---
## Iteration 6: [Pending]
*To be filled as implementation progresses...*