@akai-mirai/report-ui 1.0.0

package/README.md

@@ -0,0 +1,249 @@
+# @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
+
+```bash
+# 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:
+
+```bash
+yarn add react react-dom
+```
+
+## Quick Start
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```bash
+# 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:
+
+```typescript
+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.