Polly/docs/EXERCISES.md

# Vocabulary Exercises Documentation

This document explains how the exercise system works in the Polly vocabulary learning app.

## Overview

The exercise system allows users to practice vocabulary through various interactive exercise types. Users can configure and start exercises from different screens, track their progress, and review their results.

## Exercise Types

The app supports four different exercise types:

### 1. Guessing Exercise (Flashcard Mode)

**How it works:**
- A vocabulary card is displayed with one side (word or translation)
- The user sees only one side of the card initially
- The user guesses the answer before flipping the card

**User actions:**
- Tap "Flip Card" to reveal the answer
- Mark as "Wrong" or "Correct" after revealing
- The card advances when "Next" is tapped

**Use case:** Ideal for quick recognition practice and memorization.

---

### 2. Spelling Exercise

**How it works:**
- A vocabulary word is displayed as a prompt
- The user must type the translation manually
- The app checks if the typed answer is correct

**User actions:**
- Type the translation in the text field
- Tap "Check" to submit the answer
- See immediate feedback on correctness
- Tap "Next" to proceed to the next card

**Use case:** Excellent for practicing proper spelling and reinforcing memory through active recall.

---

### 3. Multiple Choice Exercise

**How it works:**
- A word is displayed with four answer options
- Only one option is the correct translation
- The user selects their answer

**User actions:**
- Tap one of the four options
- The correct answer is highlighted after selection
- Visual feedback shows if the choice was right or wrong
- Tap "Next" to continue

**Use case:** Good for recognition practice with immediate feedback.

---

### 4. Word Jumble Exercise

**How it works:**
- A word's letters are scrambled and displayed
- The user must click letters in the correct order to form the word
- Letters can be moved between the "available" and "assembled" areas

**User actions:**
- Click a letter from the available pool to add it to the assembly area
- Click an assembled letter to return it to the pool
- Tap "Check" when the word is assembled
- The correct answer is revealed if incorrect

**Use case:** Great for reinforcing spelling through active manipulation of letter order.

---

## Starting an Exercise

### Entry Points

1. **Dashboard Widget:** Tap "Start Exercise" from the ModernStartButtons widget
2. **Category Detail Screen:** Tap "Start" on a specific category
3. **Main Vocabulary Screen:** Tap the FAB (Floating Action Button)
4. **Daily Exercise:** Access from the dashboard for daily review

### Configuration Options

Before starting an exercise, users can configure:

| Option | Description |
|--------|-------------|
| **Number of Cards** | Slider to select how many cards to practice (1 to total available) |
| **Quick Select** | Preset buttons for 10, 25, 50, or 100 cards |
| **Language Direction** | Choose origin and target languages |
| **Exercise Types** | Select which exercise types to include (can combine multiple) |
| **Shuffle Cards** | Randomize card order |
| **Shuffle Languages** | Randomize which side (word/translation) is shown |
| **Training Mode** | Practice without affecting progress/stages |
| **Due Today Only** | Limit to items scheduled for today |

---

## Exercise Flow

```
┌─────────────────┐
│   START SCREEN  │
│ (Configuration) │
└────────┬────────┘
         │ Tap "Start Exercise"
         ▼
┌─────────────────┐
│   EXERCISE      │
│   PROGRESS      │
│   INDICATOR     │
├─────────────────┤
│   CARD/QUESTION  │
│   DISPLAY       │
├─────────────────┤
│   CONTROLS      │
│ (Reveal/Check)  │
└────────┬────────┘
         │ Complete all cards
         ▼
┌─────────────────┐
│   RESULT SCREEN │
│   (Score,       │
│    Retry,       │
│    Start Over)  │
└─────────────────┘
```

---

## Exercise Progress Indicator

During an exercise, a progress bar shows:

- **Green section:** Number of correct answers
- **Red section:** Number of wrong answers
- **Total:** Total cards in the exercise
- **Close button:** Exit the exercise (shows confirmation dialog)

The progress bar animates as the user advances through cards.

---

## Exercise State Management

The app uses a state machine to manage exercise progress:

### States

| State | Description |
|-------|-------------|
| `START` | Configuration screen before starting |
| `EXERCISE` | Active exercise in progress |
| `RESULT` | Exercise completed, showing results |

### State Transitions

```
START → EXERCISE (user taps "Start")
EXERCISE → RESULT (all cards completed)
RESULT → START (user taps "Start Over")
RESULT → EXERCISE (user taps "Retry Wrong")
```

---

## Exercise Actions

The following user actions are available during exercises:

| Action | Description |
|--------|-------------|
| `Reveal` | Show the answer (Guessing exercise) |
| `Submit` | Submit an answer (Spelling, Multiple Choice, Word Jumble) |
| `Next` | Move to the next card |
| `UpdateWordJumble` | Modify assembled letters (Word Jumble) |

---

## Results Screen

After completing an exercise, users see:

### Displayed Information
- **Percentage Score:** Overall performance as a circular progress indicator
- **Correct/Wrong Count:** Detailed breakdown of answers
- **Total Items:** Number of cards practiced

### Available Actions
- **Start Over:** Begin a new exercise from scratch
- **Repeat Wrong:** Retry only the incorrectly answered cards
- **Finish:** Return to the main screen

---

## Training Mode

When Training Mode is enabled:
- Answers are not recorded for progress tracking
- No stage progression occurs
- Useful for casual practice or testing knowledge

When disabled (default):
- Correct answers may advance item stages
- Progress is saved for statistics
- Affects due dates and learning progress

---

## Technical Architecture

### Key Components

1. **VocabularyExerciseHostScreen.kt**
   - Main container managing exercise flow
   - Handles screen states (START, EXERCISE, RESULT)
   - Coordinates between configuration and exercise screens

2. **VocabularyExercise.kt**
   - Defines exercise types (enum)
   - State classes for each exercise type
   - Action sealed class for user interactions

3. **VocabularyExerciseRenderer.kt**
   - Renders the appropriate UI based on exercise state
   - Handles display logic for each exercise type

4. **ExerciseControls.kt**
   - Input field and buttons for user interaction
   - Different controls based on exercise type

5. **ExerciseProgressIndicator.kt**
   - Visual progress bar during exercises
   - Animated updates for correct/wrong counts

---

## Related Screens

| Screen | Purpose |
|--------|---------|
| `StartScreen` | Configure exercise settings before starting |
| `ResultScreen` | Show final score and options to continue |
| `CategoryDetailScreen` | Start exercise for a specific category |
| `DashboardContent` | Main dashboard with exercise shortcuts |

---

## Tips for Users

1. **Combine exercise types:** Mix Guessing, Spelling, and Word Jumble for variety
2. **Use Training Mode:** For casual practice without affecting progress
3. **Start small:** Use 10-25 cards initially, increase as comfortable
4. **Review wrong answers:** Use "Repeat Wrong" to focus on difficult items
5. **Daily exercises:** Use "Due Today Only" for spaced repetition practice

---

## Navigation During Exercise

- **Close button:** Exit exercise (confirms before closing)
- **Back button:** Also triggers exit confirmation
- Results screen options: Continue practicing or return to dashboard