@ems/report-ui

Beautiful React-based report generation library for quiz and session results. Built with Material-UI and TypeScript.

Features

• 📊 Quiz Results Reports - Comprehensive analytics for all students
• 📝 Session Results Reports - Detailed individual student reports
• 🎨 Beautiful UI - Modern design matching your platform's style
• 🌍 Internationalization - Support for Kazakh, Russian, and English
• 📄 PDF Export - Generate PDF reports using Puppeteer
• 📈 Analytics - Question analysis, subject statistics, and more
• 🎯 TypeScript - Full type safety

Installation

# Using yarn
yarn add @ems/report-ui

# Using npm
npm install @ems/report-ui

Peer Dependencies

This library requires React and React DOM to be installed in your project:

yarn add react react-dom

Quick Start

import { renderReportToHTML } from '@ems/report-ui'
import type { QuizData, SessionData } from '@ems/report-ui'

// Generate HTML for quiz results report
const html = renderReportToHTML({
  type: 'QUIZ_RESULTS',
  quiz: quizData,
  allSessions: sessionsData,
  options: {
    language: 'ru', // 'kk' | 'ru' | 'en'
    includeProctoring: true,
    includeAiAnalysis: true
  }
})

// Use with Puppeteer to generate PDF
// (see backend integration example)

Usage

Quiz Results Report

import { QuizResultsReportSSR } from '@ems/report-ui'
import { ReportWrapper } from '@ems/report-ui'

function App() {
  return (
    <ReportWrapper>
      <QuizResultsReportSSR
        quiz={quizData}
        allSessions={sessionsData}
        options={{ language: 'ru' }}
      />
    </ReportWrapper>
  )
}

Session Results Report

import { SessionResultsReport } from '@ems/report-ui'
import { ReportWrapper } from '@ems/report-ui'

function App() {
  return (
    <ReportWrapper>
      <SessionResultsReport
        session={sessionData}
        options={{
          language: 'ru',
          includeDetailedAnswers: true,
          includeProctoring: true,
          includeAiAnalysis: true
        }}
      />
    </ReportWrapper>
  )
}

API Reference

Components

QuizResultsReportSSR

Comprehensive quiz results report for teachers.

Props:

• quiz: QuizData - Quiz data
• allSessions: SessionData[] - All student sessions
• options?: ReportGenerationOptions - Report options

SessionResultsReport

Detailed individual session results report.

Props:

• session: SessionData - Session data with answers
• options?: ReportGenerationOptions - Report options

ReportWrapper

Theme provider wrapper for reports.

Props:

• children: React.ReactNode - Report components

Utilities

renderReportToHTML(options)

Renders a report to HTML string for PDF generation.

Parameters:

• options.type: 'QUIZ_RESULTS' | 'SESSION_RESULTS' - Report type
• options.quiz?: QuizData - Quiz data (for QUIZ_RESULTS)
• options.allSessions?: SessionData[] - All sessions (for QUIZ_RESULTS)
• options.session?: SessionData - Session data (for SESSION_RESULTS)
• options.options?: ReportGenerationOptions - Report generation options

Returns: string - HTML string

Types

interface QuizData {
  id: string
  title: string
  description?: string
  startTime?: Date | string
  endTime?: Date | string
  duration?: number
  status?: string
  locale?: string
  quizSubjects?: Array<{ subject?: { title: Record<string, string> } }>
  author?: { firstName?: string; lastName?: string; email?: string }
  _count?: { questions: number }
  questions?: Array<{ question: QuestionData }>
}

interface SessionData {
  id: string
  status: string
  score?: number
  correctAnswers?: number
  totalQuestions?: number
  timeSpent?: number
  finishedAt?: Date | string
  startedAt?: Date | string
  user: { firstName?: string; lastName?: string; userName?: string; email?: string }
  quiz?: { title?: string; quizSubjects?: Array<{ subject?: { title: Record<string, string> } }> }
  answers?: AnswerData[]
  proctoringMetrics?: { riskScore?: number }
  proctoringAlerts?: Array<{ severity?: string; type?: string; message?: string; timestamp?: Date | string }>
  aiAnalysis?: { summary?: string; recommendations?: string }
}

interface ReportGenerationOptions {
  includeAiAnalysis?: boolean
  includeProctoring?: boolean
  includeDetailedAnswers?: boolean
  language?: 'kk' | 'ru' | 'en'
  format?: 'PDF' | 'IMAGE'
}

Development

Setup

# Install dependencies
yarn install

# Start dev server (for preview)
yarn dev

# Build library
yarn build:lib

Project Structure

src/
  ├── components/          # React components
  │   ├── QuizResultsReportSSR.tsx
  │   ├── SessionResultsReport.tsx
  │   ├── SubjectStatistics.tsx
  │   └── QuestionAnalysis.tsx
  ├── utils/              # Utilities
  │   ├── render.tsx      # HTML rendering
  │   └── format.ts       # Formatting helpers
  ├── types/              # TypeScript types
  ├── theme/              # Material-UI theme
  ├── i18n/               # Internationalization
  └── index.ts            # Main entry point

Backend Integration

See INTEGRATION_GUIDE.md for detailed backend integration instructions.

Example with NestJS:

import { renderReportToHTML } from '@ems/report-ui'
import puppeteer from 'puppeteer'

async function generatePDF(quizData: QuizData, sessions: SessionData[]) {
  const html = renderReportToHTML({
    type: 'QUIZ_RESULTS',
    quiz: quizData,
    allSessions: sessions,
    options: { language: 'ru' }
  })

  const browser = await puppeteer.launch()
  const page = await browser.newPage()
  await page.setContent(html)
  const pdf = await page.pdf({ format: 'A4' })
  await browser.close()

  return pdf
}

License

MIT

Support

For issues and questions, please contact the EMS team.