mcp-quiz-server/public/js/types/index.ts

🧠 AI-Powered Quiz Management via Model Context Protocol (MCP) - Create, manage, and take quizzes directly from VS Code, Claude, and other AI agents.

/**
 * @fileoverview Core type definitions for the Quiz Platform
 * @version 2.0.0
 * @requirementsTraceability {@link Requirements.REQ_ARCH_003} - Type safety and interface definitions
 * @requirementsTraceability {@link Requirements.REQ_DATA_001} - Quiz data structure and schema definitions
 * @requirementsTraceability {@link Requirements.REQ_QUIZ_001} - Quiz structure and question format specifications
 */

export interface Quiz {
  id: string;
  title: string;
  description?: string;
  category?: string;
  difficulty?: string;
  estimatedTime?: number;
  questions: Question[];
  createdAt?: string;
  updatedAt?: string;
}

export interface Question {
  id: string;
  question: string;
  options: string[];
  correctAnswer: string;
  explanation?: string;
  points?: number;
  category?: string;
  difficulty?: string;
}

export interface QuizResult {
  quizId: string;
  score: number;
  totalQuestions: number;
  percentage: number;
  timeSpent?: number;
  results: QuestionResult[];
  feedback?: QuestionFeedback[];
}

export interface QuestionFeedback {
  questionId: string;
  question: string;
  userAnswer: string;
  correctAnswer: string;
  isCorrect: boolean;
  explanation: string;
  options: string[];
}

export interface QuestionResult {
  questionId: string;
  question: string;
  userAnswer: string;
  correctAnswer: string;
  isCorrect: boolean;
  explanation?: string;
  timeSpent?: number;
}

export interface ThemeConfig {
  mode: 'light' | 'dark' | 'system';
  color: 'slate' | 'blue' | 'purple' | 'emerald' | 'rose' | 'orange';
}

export interface User {
  id: string;
  username: string;
  email?: string;
  role?: string;
  createdAt?: string;
}

export interface AppState {
  quizzes: Quiz[];
  currentQuiz: Quiz | null;
  filteredQuizzes: Quiz[];
  userAnswers: Record<string, string>;
  currentFilter: string;
  searchTerm: string;
  theme: ThemeConfig;
  settings: AppSettings;
  auth: {
    isAuthenticated: boolean;
    user: User | null;
    token: string | null;
    isLoading: boolean;
    error: string | null;
    showLoginModal: boolean;
  };
  ui: {
    loading: boolean;
    showWelcome: boolean;
    showResults: boolean;
    showCelebration: boolean;
    viewMode: ViewMode;
    submitBarVisible: boolean;
  };
  quiz: {
    completedQuizzes: Set<string>;
    quizProgress: Record<string, QuizProgress>;
    isCompleted: boolean;
    currentQuestionIndex: number;
  };
  lastResult: QuizResult | null;
}

export type FilterType = 'all' | 'recent' | 'favorites';
export type ViewMode = 'single' | 'list';
export type ThemeMode = 'light' | 'dark' | 'system';
export type ThemeColor = 'slate' | 'blue' | 'purple' | 'emerald' | 'rose' | 'orange';

// Settings interfaces for configuration system
export interface AppSettings {
  ui: UISettings;
  quiz: QuizSettings;
  accessibility: AccessibilitySettings;
  performance: PerformanceSettings;
}

export interface UISettings {
  theme: string;
  fontSize: 'small' | 'medium' | 'large';
  navigationVisible: boolean;
  reducedMotion: boolean;
  animations: boolean;
  celebration: boolean;
  announceChanges: boolean;
}

export interface QuizSettings {
  viewMode: ViewMode;
  autoAdvance: {
    enabled: boolean;
    delaySeconds: number;
    showCountdown: boolean;
  };
  showProgress: boolean;
  largeButtons: boolean;
  preloadQuestions: boolean;
  minimalUI: boolean;
}

export interface AccessibilitySettings {
  screenReaderMode: boolean;
  keyboardNavigation: boolean;
  skipLinks: boolean;
  highContrast: boolean;
}

export interface PerformanceSettings {
  lazyLoading: boolean;
  compactMode: boolean;
  disableAnalytics: boolean;
  cacheOptimized: boolean;
}

// Quiz progress and completion tracking
export interface QuizProgress {
  quizId: string;
  status: 'available' | 'in-progress' | 'completed' | 'paused';
  currentQuestion?: number;
  answers: Record<string, string>;
  startedAt?: Date;
  completedAt?: Date;
  score?: number;
  timeSpent?: number;
}

// Demo configuration interface
export interface DemoConfig {
  name: string;
  description: string;
  settings: Partial<AppSettings>;
  metadata?: {
    createdBy?: string;
    purpose?: string;
    tags?: string[];
    lastUpdated?: string;
    version?: string;
  };
}