kaboot/docs/QUIZ_EDITOR_PLAN.md

Quiz Editor Feature Plan

Overview

Add the ability to view and edit quizzes:

1. Post-generation editing - Review/edit AI-generated quizzes before starting a game
2. Library editing - Edit saved quizzes from the quiz library

Current Flow

AI Generation → Lobby (with save prompt) → Start Game
Library Load → Lobby → Start Game

Proposed Flow

AI Generation → Quiz Editor → Lobby (with save prompt) → Start Game
Library Load → Quiz Editor → Lobby → Start Game
                    ↓
              Save changes back to library (if from library)

User Stories

1. As a host, I want to review AI-generated questions before starting a game so I can remove inappropriate or incorrect questions
2. As a host, I want to edit question text and answers to fix mistakes or improve clarity
3. As a host, I want to delete questions I don't want to include
4. As a host, I want to add new questions to an AI-generated or saved quiz
5. As a host, I want to reorder questions
6. As a host, I want to edit quizzes from my library and save changes

UI Design

Quiz Editor Screen

┌─────────────────────────────────────────────────────────────┐
│  ← Back                              [Save to Library]      │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Quiz Title (editable)                        ✏️    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Questions (12)                          [+ Add Question]   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ ≡  1. What is the capital of France?          ✏️ 🗑️ │   │
│  │     ○ London  ○ Berlin  ● Paris  ○ Madrid          │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ ≡  2. Which planet is known as the Red Planet? ✏️ 🗑️│   │
│  │     ○ Venus  ● Mars  ○ Jupiter  ○ Saturn           │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ... (scrollable list)                                      │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │            [Start Game with 12 Questions]            │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Question Edit Modal

┌─────────────────────────────────────────────────────────────┐
│  Edit Question                                        ✕     │
│                                                             │
│  Question Text                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ What is the capital of France?                      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Time Limit: [20] seconds                                   │
│                                                             │
│  Options (select correct answer)                            │
│                                                             │
│  ○ ┌──────────────────────────────────────────┐  🗑️        │
│    │ London                                   │            │
│    └──────────────────────────────────────────┘            │
│    Reason: ┌──────────────────────────────────┐            │
│            │ London is the capital of the UK  │            │
│            └──────────────────────────────────┘            │
│                                                             │
│  ● ┌──────────────────────────────────────────┐  🗑️        │
│    │ Paris                                    │            │
│    └──────────────────────────────────────────┘            │
│    Reason: ┌──────────────────────────────────┐            │
│            │ Paris has been France's capital  │            │
│            │ since the 10th century           │            │
│            └──────────────────────────────────┘            │
│  ...                                                        │
│                                                             │
│  [+ Add Option]                                             │
│                                                             │
│  ┌───────────────┐  ┌───────────────────────────────────┐  │
│  │    Cancel     │  │             Save Changes          │  │
│  └───────────────┘  └───────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Implementation Phases

Phase 1: Quiz Editor Component

New files:

• components/QuizEditor.tsx - Main editor screen
• components/QuestionCard.tsx - Collapsible question display card
• components/QuestionEditModal.tsx - Modal for editing a single question

Features:

• Display quiz title (editable inline)
• List all questions in collapsible cards
• Show question text and options in collapsed view
• Expand to see answer reasons
• Edit/delete buttons per question
• Drag handle for reordering (optional, Phase 2)

Phase 2: Question Editing

Features:

• Edit question text
• Edit option text and reasons
• Change correct answer (radio button)
• Delete options (minimum 2 required)
• Add new options (maximum 6)
• Edit time limit per question
• Validation before save

Phase 3: Add/Delete Questions

Features:

• Delete question with confirmation
• Add new blank question
• Duplicate existing question
• Minimum 1 question required to start game

Phase 4: Drag-and-Drop Reordering

Dependencies:

• @dnd-kit/core and @dnd-kit/sortable (already may be available, or add)

Features:

• Drag handle on each question card
• Visual feedback during drag
• Reorder questions in the list

Phase 5: Integration with Flows

Modifications to existing files:

1. App.tsx

   • Add EDITING game state
   • Route to QuizEditor after generation or library load
   • Pass quiz and callbacks to editor

2. hooks/useGame.ts

   • Add editQuiz() function to update quiz state
   • Add startGameFromEditor() to proceed to lobby
   • Track if quiz came from library (for save-back)

3. types.ts

   • Add EDITING to GameState type

4. components/QuizLibrary.tsx

   • Change "Load" to open editor instead of going directly to lobby
   • Or add separate "Edit" button alongside "Load"

Phase 6: Save Changes to Library

Features:

• "Save to Library" button in editor
• If quiz was loaded from library, offer "Save Changes" (PUT)
• If quiz is new (AI-generated), offer "Save as New" (POST)
• Show save confirmation toast

API:

• Existing PUT /api/quizzes/:id endpoint already supports updates

State Management

// New state in useGame or separate useQuizEditor hook
interface EditorState {
  originalQuiz: Quiz | null;      // For detecting changes
  editedQuiz: Quiz;               // Current working copy
  sourceQuizId: string | null;    // If loaded from library
  hasUnsavedChanges: boolean;
  validationErrors: string[];
}

File Changes Summary

File	Changes
components/QuizEditor.tsx	NEW - Main editor component
components/QuestionCard.tsx	NEW - Question display card
components/QuestionEditModal.tsx	NEW - Edit modal
App.tsx	Add EDITING state routing
hooks/useGame.ts	Add editor-related functions
types.ts	Add EDITING to GameState
components/QuizLibrary.tsx	Add edit button/flow

Validation Rules

1. Quiz must have a title
2. Quiz must have at least 1 question
3. Each question must have text
4. Each question must have 2-6 options
5. Each question must have exactly 1 correct answer
6. Each option must have text
7. Time limit must be 5-60 seconds

Edge Cases

1. Empty quiz from AI - Show error, allow retry or manual add
2. Unsaved changes on back - Confirm dialog "Discard changes?"
3. Delete last question - Prevent, show error
4. Delete correct answer option - Auto-select another as correct, or prevent
5. Network error on save - Show error toast, keep editor open

Future Enhancements (Out of Scope)

• Image support in questions
• Bulk import/export (JSON, CSV)
• Question bank / templates
• Collaborative editing
• Version history