Render Grid & Basic Touch Events

[lukeKilpatrick-minitap]

Description
Render the grid on the mobile screen and handle basic tap detection.

Requirements

• Render the 2D array as a grid of squares (CSS Grid, Canvas, or View components).
• Ensure the grid fits within the viewport width (for Portrait).
• Implement onTap handler:
  • If cell is covered, call the Reveal logic.
  • If cell is mined, trigger (console log) Game Over.

[traycerai]

Plan

Observations

The workspace is a greenfield mobile Minesweeper project with no existing source code. The README indicates a mobile-first approach with classic Minesweeper gameplay, dig/flag toggle controls, and quality-of-life features. The ticket focuses on rendering the game grid and implementing basic tap detection for cell interaction. No specific framework has been chosen yet, though the requirements mention CSS Grid, Canvas, or View components as options.

Approach

Since this is a new project, the plan will establish the foundational grid rendering system and touch event handling. The approach prioritizes a component-based architecture that separates presentation (grid rendering) from logic (game state). The grid will be rendered responsively to fit portrait viewport width, with tap handlers that distinguish between covered/revealed cells and trigger appropriate game actions (reveal or game over).

Implementation Steps

1. Project Setup & Technology Stack Selection

Decision Point: Choose the mobile development framework based on team expertise and requirements:

• React Native: For cross-platform native apps with View components
• React/PWA: For web-based mobile-first experience with CSS Grid
• Flutter: For high-performance cross-platform with Canvas-like rendering

Initialize the project with the chosen framework and set up the basic app structure with routing/navigation if needed.

2. Game State Structure

Define the data model for the grid as a 2D array where each cell contains:

• isMined: boolean indicating if cell contains a mine
• isRevealed: boolean indicating if cell is uncovered
• isFlagged: boolean indicating if cell is flagged
• adjacentMines: number (0-8) of neighboring mines
• row: number, cell row index
• col: number, cell column index

Create a state management solution (Context API, Redux, Zustand, or framework-specific) to hold:

• grid: 2D array of cell objects
• gameStatus: enum ('playing', 'won', 'lost')
• mode: enum ('dig', 'flag') for the toggle mentioned in README

3. Grid Component Implementation

Create a Grid or GameBoard component that:

Props:

• grid: 2D array of cell data
• onCellTap: callback function (row, col) => void
• gameStatus: current game state

Rendering Strategy (choose based on framework):

Option A - CSS Grid (React/PWA):

• Use CSS Grid with grid-template-columns: repeat(cols, 1fr)
• Calculate cell size: cellSize = (viewportWidth - padding) / numberOfColumns
• Set aspect-ratio: 1 on cells to maintain squares
• Use max-width: 100vw and box-sizing: border-box

Option B - View Components (React Native):

• Use FlatList with numColumns prop or nested View with flexDirection: 'row'
• Calculate cell dimensions using Dimensions.get('window').width
• Use aspectRatio: 1 style property
• Wrap in ScrollView for larger grids

Option C - Canvas (any framework):

• Use HTML5 Canvas or framework equivalent
• Calculate grid dimensions and cell size based on viewport
• Implement custom drawing logic for cells
• Handle touch-to-coordinate conversion

4. Cell Component Implementation

Create a Cell or GridCell component that:

Props:

• cell: cell data object
• onTap: callback function
• size: calculated cell dimension

Visual States:

• Covered: Default gray/dark background, slightly raised appearance
• Revealed Empty (0 adjacent mines): Light background, flat
• Revealed Numbered (1-8 adjacent): Light background with centered number, color-coded by count
• Revealed Mine: Red background with mine icon/symbol
• Flagged: Covered appearance with flag icon overlay

Styling:

• Use border or shadow to create grid lines
• Apply touchable properties (e.g., TouchableOpacity in RN, cursor: pointer in web)
• Add visual feedback on press (opacity change, scale animation)

5. Responsive Grid Layout

Implement viewport-aware sizing:

For Portrait Orientation:

Calculate:
- viewportWidth = screen width
- gridPadding = 16-24px (safe margins)
- availableWidth = viewportWidth - (2 * gridPadding)
- cellSize = availableWidth / numberOfColumns
- gridHeight = cellSize * numberOfRows

Responsive Container:

• Center the grid horizontally
• Add vertical scrolling if grid height exceeds viewport
• Maintain aspect ratio for cells
• Use SafeAreaView (React Native) or CSS safe-area-inset for notched devices

6. Touch Event Handler Implementation

Implement onCellTap handler in the parent component or game controller:

Handler Logic:

function handleCellTap(row, col):
  1. Check if game is over (gameStatus !== 'playing')
     - If true, return early (ignore taps)
  
  2. Get cell at grid[row][col]
  
  3. Check if cell is already revealed
     - If true, return early (or handle chording for future)
  
  4. Check if cell is flagged
     - If true and mode is 'dig', return early (flags prevent accidental digs)
  
  5. If mode is 'flag':
     - Toggle cell.isFlagged
     - Update grid state
     - Return
  
  6. If mode is 'dig':
     - If cell.isMined:
       * Set gameStatus to 'lost'
       * Console.log("Game Over - Mine hit!")
       * Reveal all mines (optional visual feedback)
     - Else:
       * Call revealCell(row, col) logic
       * Check win condition

Event Binding (framework-specific):

• React Native: Use onPress prop on TouchableOpacity or Pressable
• React/Web: Use onClick handler with touch event support
• Add event.preventDefault() to prevent default touch behaviors (zoom, scroll)

7. Reveal Logic Integration

Create or integrate with revealCell function:

Basic Reveal:

function revealCell(row, col):
  1. Set grid[row][col].isRevealed = true
  
  2. If grid[row][col].adjacentMines === 0:
     - Implement flood fill algorithm
     - Recursively reveal all adjacent cells
     - Stop at numbered cells (don't recurse beyond them)
  
  3. Update grid state to trigger re-render

Flood Fill Algorithm (for 0-mine cells):

• Use BFS (queue) or DFS (recursion) to expand
• Check 8 directions (N, NE, E, SE, S, SW, W, NW)
• Mark cells as visited to avoid infinite loops
• Reveal numbered border cells but don't expand through them

8. Visual Feedback & Polish

Add user experience enhancements:

Touch Feedback:

• Scale animation on tap (0.95 scale)
• Opacity change (0.7) during press
• Haptic feedback on reveal (if supported)

Reveal Animation:

• Fade-in animation for revealed cells
• Staggered animation for flood-fill reveals
• Shake animation for mine hit

Grid Appearance:

• Subtle shadows for depth
• Color-coded numbers (1=blue, 2=green, 3=red, etc.)
• Clear visual distinction between states

9. Testing Considerations

Manual Testing Checklist:

• Grid renders correctly on different screen sizes
• Cells are tappable and responsive
• Covered cells reveal on tap
• Mine cells trigger game over with console log
• Grid fits within portrait viewport without horizontal scroll
• Touch events don't conflict with system gestures

Edge Cases:

• Tapping revealed cells (should be no-op)
• Tapping during game over state
• Very small grids (e.g., 5x5)
• Large grids (e.g., 30x16 Expert mode)
• Rapid successive taps

10. Integration Points

Connect to Future Features:

• Mode toggle button (dig/flag) - pass current mode to tap handler
• Timer component - start on first tap
• Mine counter - update when flags are placed
• Game over modal - trigger on mine hit instead of just console.log
• Win detection - check after each reveal if all non-mine cells are revealed

State Management Hooks:

• Expose resetGame() function for new game button
• Expose pauseGame() / resumeGame() for pause feature
• Store grid state for persistence (future feature)

Architecture Diagram

sequenceDiagram
    participant User
    participant Grid
    participant Cell
    participant GameController
    participant GameState

    User->>Cell: Tap cell
    Cell->>Grid: onCellTap(row, col)
    Grid->>GameController: handleCellTap(row, col)
    GameController->>GameState: Get cell data
    GameState-->>GameController: cell object
    
    alt Cell is mined
        GameController->>GameState: Set gameStatus = 'lost'
        GameController->>Console: log("Game Over")
        GameController->>GameState: Reveal all mines
    else Cell is safe
        GameController->>GameState: revealCell(row, col)
        GameState->>GameState: Flood fill if adjacentMines = 0
        GameState->>GameState: Check win condition
    end
    
    GameState-->>Grid: Updated grid state
    Grid-->>Cell: Re-render with new state
    Cell-->>User: Visual feedback

Loading

File Structure Recommendation

src/
├── components/
│   ├── Grid.{jsx|tsx|dart}          # Main grid container
│   ├── Cell.{jsx|tsx|dart}          # Individual cell component
│   └── GameBoard.{jsx|tsx|dart}     # Wrapper with game controls
├── hooks/ or utils/
│   ├── useGameState.{js|ts}         # State management hook
│   └── gameLogic.{js|ts}            # Reveal, flood-fill, win detection
├── constants/
│   └── gameConfig.{js|ts}           # Cell colors, sizes, difficulty presets
└── screens/
    └── GameScreen.{jsx|tsx|dart}    # Main game screen

Import In IDE

🤖 Prompt for AI Agents

## Observations

The workspace is a greenfield mobile Minesweeper project with no existing source code. The README indicates a mobile-first approach with classic Minesweeper gameplay, dig/flag toggle controls, and quality-of-life features. The ticket focuses on rendering the game grid and implementing basic tap detection for cell interaction. No specific framework has been chosen yet, though the requirements mention CSS Grid, Canvas, or View components as options.

## Approach

Since this is a new project, the plan will establish the foundational grid rendering system and touch event handling. The approach prioritizes a component-based architecture that separates presentation (grid rendering) from logic (game state). The grid will be rendered responsively to fit portrait viewport width, with tap handlers that distinguish between covered/revealed cells and trigger appropriate game actions (reveal or game over).

## Implementation Steps

### 1. Project Setup & Technology Stack Selection

**Decision Point**: Choose the mobile development framework based on team expertise and requirements:
- **React Native**: For cross-platform native apps with View components
- **React/PWA**: For web-based mobile-first experience with CSS Grid
- **Flutter**: For high-performance cross-platform with Canvas-like rendering

Initialize the project with the chosen framework and set up the basic app structure with routing/navigation if needed.

### 2. Game State Structure

Define the data model for the grid as a 2D array where each cell contains:
- `isMined`: boolean indicating if cell contains a mine
- `isRevealed`: boolean indicating if cell is uncovered
- `isFlagged`: boolean indicating if cell is flagged
- `adjacentMines`: number (0-8) of neighboring mines
- `row`: number, cell row index
- `col`: number, cell column index

Create a state management solution (Context API, Redux, Zustand, or framework-specific) to hold:
- `grid`: 2D array of cell objects
- `gameStatus`: enum ('playing', 'won', 'lost')
- `mode`: enum ('dig', 'flag') for the toggle mentioned in README

### 3. Grid Component Implementation

Create a `Grid` or `GameBoard` component that:

**Props**:
- `grid`: 2D array of cell data
- `onCellTap`: callback function `(row, col) => void`
- `gameStatus`: current game state

**Rendering Strategy** (choose based on framework):

**Option A - CSS Grid** (React/PWA):
- Use CSS Grid with `grid-template-columns: repeat(cols, 1fr)`
- Calculate cell size: `cellSize = (viewportWidth - padding) / numberOfColumns`
- Set `aspect-ratio: 1` on cells to maintain squares
- Use `max-width: 100vw` and `box-sizing: border-box`

**Option B - View Components** (React Native):
- Use `FlatList` with `numColumns` prop or nested `View` with `flexDirection: 'row'`
- Calculate cell dimensions using `Dimensions.get('window').width`
- Use `aspectRatio: 1` style property
- Wrap in `ScrollView` for larger grids

**Option C - Canvas** (any framework):
- Use HTML5 Canvas or framework equivalent
- Calculate grid dimensions and cell size based on viewport
- Implement custom drawing logic for cells
- Handle touch-to-coordinate conversion

### 4. Cell Component Implementation

Create a `Cell` or `GridCell` component that:

**Props**:
- `cell`: cell data object
- `onTap`: callback function
- `size`: calculated cell dimension

**Visual States**:
- **Covered**: Default gray/dark background, slightly raised appearance
- **Revealed Empty** (0 adjacent mines): Light background, flat
- **Revealed Numbered** (1-8 adjacent): Light background with centered number, color-coded by count
- **Revealed Mine**: Red background with mine icon/symbol
- **Flagged**: Covered appearance with flag icon overlay

**Styling**:
- Use `border` or `shadow` to create grid lines
- Apply `touchable` properties (e.g., `TouchableOpacity` in RN, `cursor: pointer` in web)
- Add visual feedback on press (opacity change, scale animation)

### 5. Responsive Grid Layout

Implement viewport-aware sizing:

**For Portrait Orientation**:
```
Calculate:
- viewportWidth = screen width
- gridPadding = 16-24px (safe margins)
- availableWidth = viewportWidth - (2 * gridPadding)
- cellSize = availableWidth / numberOfColumns
- gridHeight = cellSize * numberOfRows
```

**Responsive Container**:
- Center the grid horizontally
- Add vertical scrolling if grid height exceeds viewport
- Maintain aspect ratio for cells
- Use `SafeAreaView` (React Native) or CSS safe-area-inset for notched devices

### 6. Touch Event Handler Implementation

Implement `onCellTap` handler in the parent component or game controller:

**Handler Logic**:
```
function handleCellTap(row, col):
  1. Check if game is over (gameStatus !== 'playing')
     - If true, return early (ignore taps)
  
  2. Get cell at grid[row][col]
  
  3. Check if cell is already revealed
     - If true, return early (or handle chording for future)
  
  4. Check if cell is flagged
     - If true and mode is 'dig', return early (flags prevent accidental digs)
  
  5. If mode is 'flag':
     - Toggle cell.isFlagged
     - Update grid state
     - Return
  
  6. If mode is 'dig':
     - If cell.isMined:
       * Set gameStatus to 'lost'
       * Console.log("Game Over - Mine hit!")
       * Reveal all mines (optional visual feedback)
     - Else:
       * Call revealCell(row, col) logic
       * Check win condition
```

**Event Binding** (framework-specific):
- React Native: Use `onPress` prop on `TouchableOpacity` or `Pressable`
- React/Web: Use `onClick` handler with touch event support
- Add `event.preventDefault()` to prevent default touch behaviors (zoom, scroll)

### 7. Reveal Logic Integration

Create or integrate with `revealCell` function:

**Basic Reveal**:
```
function revealCell(row, col):
  1. Set grid[row][col].isRevealed = true
  
  2. If grid[row][col].adjacentMines === 0:
     - Implement flood fill algorithm
     - Recursively reveal all adjacent cells
     - Stop at numbered cells (don't recurse beyond them)
  
  3. Update grid state to trigger re-render
```

**Flood Fill Algorithm** (for 0-mine cells):
- Use BFS (queue) or DFS (recursion) to expand
- Check 8 directions (N, NE, E, SE, S, SW, W, NW)
- Mark cells as visited to avoid infinite loops
- Reveal numbered border cells but don't expand through them

### 8. Visual Feedback & Polish

Add user experience enhancements:

**Touch Feedback**:
- Scale animation on tap (0.95 scale)
- Opacity change (0.7) during press
- Haptic feedback on reveal (if supported)

**Reveal Animation**:
- Fade-in animation for revealed cells
- Staggered animation for flood-fill reveals
- Shake animation for mine hit

**Grid Appearance**:
- Subtle shadows for depth
- Color-coded numbers (1=blue, 2=green, 3=red, etc.)
- Clear visual distinction between states

### 9. Testing Considerations

**Manual Testing Checklist**:
- Grid renders correctly on different screen sizes
- Cells are tappable and responsive
- Covered cells reveal on tap
- Mine cells trigger game over with console log
- Grid fits within portrait viewport without horizontal scroll
- Touch events don't conflict with system gestures

**Edge Cases**:
- Tapping revealed cells (should be no-op)
- Tapping during game over state
- Very small grids (e.g., 5x5)
- Large grids (e.g., 30x16 Expert mode)
- Rapid successive taps

### 10. Integration Points

**Connect to Future Features**:
- Mode toggle button (dig/flag) - pass current mode to tap handler
- Timer component - start on first tap
- Mine counter - update when flags are placed
- Game over modal - trigger on mine hit instead of just console.log
- Win detection - check after each reveal if all non-mine cells are revealed

**State Management Hooks**:
- Expose `resetGame()` function for new game button
- Expose `pauseGame()` / `resumeGame()` for pause feature
- Store grid state for persistence (future feature)

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant Grid
    participant Cell
    participant GameController
    participant GameState

    User->>Cell: Tap cell
    Cell->>Grid: onCellTap(row, col)
    Grid->>GameController: handleCellTap(row, col)
    GameController->>GameState: Get cell data
    GameState-->>GameController: cell object
    
    alt Cell is mined
        GameController->>GameState: Set gameStatus = 'lost'
        GameController->>Console: log("Game Over")
        GameController->>GameState: Reveal all mines
    else Cell is safe
        GameController->>GameState: revealCell(row, col)
        GameState->>GameState: Flood fill if adjacentMines = 0
        GameState->>GameState: Check win condition
    end
    
    GameState-->>Grid: Updated grid state
    Grid-->>Cell: Re-render with new state
    Cell-->>User: Visual feedback
```

## File Structure Recommendation

```
src/
├── components/
│   ├── Grid.{jsx|tsx|dart}          # Main grid container
│   ├── Cell.{jsx|tsx|dart}          # Individual cell component
│   └── GameBoard.{jsx|tsx|dart}     # Wrapper with game controls
├── hooks/ or utils/
│   ├── useGameState.{js|ts}         # State management hook
│   └── gameLogic.{js|ts}            # Reveal, flood-fill, win detection
├── constants/
│   └── gameConfig.{js|ts}           # Cell colors, sizes, difficulty presets
└── screens/
    └── GameScreen.{jsx|tsx|dart}    # Main game screen
```

---

Execution Information

Branch: main
Commit: 8a8f15a

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.