@thanh01.pmt/interactive-quiz-kit 1.0.2 → 1.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +206 -153
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,176 +1,229 @@
|
|
|
1
|
-
# Interactive Quiz Kit
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
###
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
6. **Short Answer (Trả lời ngắn)**
|
|
47
|
-
7. **Numeric (Trả lời bằng số)**
|
|
48
|
-
8. **Sequence (Sắp xếp thứ tự)**
|
|
49
|
-
9. **Matching (Ghép nối)** - Hiện UI Player dùng Select thay thế cho từng mục
|
|
50
|
-
10. **Hotspot (Điểm nóng trên ảnh)**
|
|
51
|
-
11. **Blockly Programming (Lập trình kéo thả khối Blockly)**
|
|
52
|
-
12. **Scratch Programming (Lập trình Scratch - sử dụng Blockly với renderer Zelos)**
|
|
53
|
-
|
|
54
|
-
### 5. Quản lý Dữ liệu Quiz
|
|
55
|
-
- **Định nghĩa Kiểu TypeScript:** Cung cấp các interface rõ ràng (\`QuizConfig\`, \`QuizQuestion\`, v.v.) cho cấu trúc dữ liệu quiz.
|
|
56
|
-
- **Nhập/Xuất JSON:** Dễ dàng lưu và tải quiz dưới dạng file JSON.
|
|
57
|
-
- **Đóng gói SCORM:**
|
|
58
|
-
- \`SCORMManifestGenerator\`: Tạo file \`imsmanifest.xml\`.
|
|
59
|
-
- \`HTMLLauncherGenerator\`: Tạo file HTML launcher cho SCORM.
|
|
60
|
-
|
|
61
|
-
### 6. Tích hợp AI (với Genkit & Gemini)
|
|
62
|
-
- Sử dụng các flow Genkit để tương tác với Gemini API.
|
|
63
|
-
- **Tạo Câu hỏi Đơn lẻ:** Các flow như \`generateMCQQuestion\`, \`generateTrueFalseQuestion\`, v.v.
|
|
64
|
-
- **Tạo Toàn bộ Quiz:**
|
|
65
|
-
- \`generate-quiz-plan-flow.ts\`: Lập kế hoạch cấu trúc quiz.
|
|
66
|
-
- \`generateQuestionsFromQuizPlanFlow.ts\`: Tạo các câu hỏi chi tiết dựa trên kế hoạch.
|
|
67
|
-
|
|
68
|
-
## Thành phần và Dịch vụ Chính
|
|
69
|
-
|
|
70
|
-
- **\`QuizPlayer.tsx\`**: Thành phần chính để người dùng làm quiz.
|
|
71
|
-
- **\`QuizAuthoringTool.tsx\`**: Giao diện chính để tạo và chỉnh sửa quiz.
|
|
72
|
-
- **\`QuizEngine.ts\`**: Lớp logic xử lý trạng thái, chấm điểm, và các hoạt động của quiz.
|
|
73
|
-
- **\`SCORMService.ts\`**: Xử lý giao tiếp với SCORM API của LMS.
|
|
74
|
-
- **\`QuestionRenderer.tsx\`**: Quyết định và hiển thị UI phù hợp cho từng loại câu hỏi.
|
|
75
|
-
- **Các thành phần UI câu hỏi (ví dụ: \`MultipleChoiceQuestionUI.tsx\`)**: Hiển thị và xử lý tương tác cho từng loại câu hỏi cụ thể.
|
|
76
|
-
- **Các form câu hỏi (ví dụ: \`MultipleChoiceQuestionForm.tsx\`)**: Được sử dụng trong \`EditQuestionModal\` để chỉnh sửa từng loại câu hỏi.
|
|
77
|
-
- **Các flow AI (trong \`src/ai/flows/\`)**: Logic Genkit để tạo nội dung quiz bằng AI.
|
|
78
|
-
|
|
79
|
-
## Cài đặt (Hướng dẫn nếu tách thành thư viện riêng)
|
|
80
|
-
|
|
81
|
-
Nếu thư viện này được publish lên npm, bạn có thể cài đặt bằng:
|
|
82
|
-
\`\`\`bash
|
|
83
|
-
npm install interactive-quiz-kit
|
|
84
|
-
# hoặc
|
|
85
|
-
yarn add interactive-quiz-kit
|
|
86
|
-
\`\`\`
|
|
87
|
-
Để phát triển local và sử dụng trong project khác, bạn có thể dùng \`npm link\`.
|
|
88
|
-
|
|
89
|
-
## Sử dụng Cơ bản (trong một ứng dụng React)
|
|
90
|
-
|
|
91
|
-
### Hiển thị Quiz cho Người dùng:
|
|
92
|
-
\`\`\`tsx
|
|
1
|
+
# Interactive Quiz Kit
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@thanh01pmt/interactive-quiz-kit)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
|
|
6
|
+
**Interactive Quiz Kit** is a comprehensive TypeScript library built with React, designed to effortlessly create, manage, play, and distribute interactive quizzes. It provides a robust core logic (`QuizEngine`), reusable React UI components, and support for a wide variety of question types.
|
|
7
|
+
|
|
8
|
+
The library is architected for easy extension and integration, featuring a powerful authoring tool, AI-powered content generation (using Google's Genkit and Gemini), and SCORM packaging for seamless LMS integration.
|
|
9
|
+
|
|
10
|
+
## ✨ Features
|
|
11
|
+
|
|
12
|
+
* **Robust Core Engine**: Handles state management, navigation, automatic grading, and time tracking.
|
|
13
|
+
* **Rich Question Support**: Includes 12+ question types, from Multiple Choice to complex ones like Blockly/Scratch Programming and Hotspot.
|
|
14
|
+
* **React-based UI Kit**: A full suite of components to build quiz players and authoring tools.
|
|
15
|
+
* `<QuizPlayer>`: The main component for taking quizzes.
|
|
16
|
+
* `<QuizAuthoringTool>`: A powerful interface for creating and editing quizzes.
|
|
17
|
+
* **Headless Mode**: Use all core logic, services, and AI flows independently of the React UI. Ideal for backend integrations, custom frontends, or automation scripts.
|
|
18
|
+
* **AI-Powered Generation**:
|
|
19
|
+
* Generate individual questions based on topic, context, and difficulty.
|
|
20
|
+
* Generate entire, well-structured quizzes using a two-stage planning and generation process.
|
|
21
|
+
* **SCORM & Webhook Integration**:
|
|
22
|
+
* Package quizzes as SCORM 1.2 or 2004 compliant ZIP files.
|
|
23
|
+
* Send detailed quiz results to a specified webhook URL.
|
|
24
|
+
|
|
25
|
+
## 🚀 Installation
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm install @thanh01pmt/interactive-quiz-kit
|
|
29
|
+
# or
|
|
30
|
+
yarn add @thanh01pmt/interactive-quiz-kit
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
**Peer Dependencies:** This library requires `react` and `react-dom` as peer dependencies. Ensure they are installed in your project.
|
|
34
|
+
|
|
35
|
+
## 📚 Usage
|
|
36
|
+
|
|
37
|
+
This library supports two primary modes of usage: with the built-in React UI, or in a "headless" mode using only the core logic.
|
|
38
|
+
|
|
39
|
+
### 1. Standard Mode (with React UI)
|
|
40
|
+
|
|
41
|
+
This is the quickest way to get a fully functional quiz application up and running.
|
|
42
|
+
|
|
43
|
+
#### Example: Displaying a Quiz with `<QuizPlayer>`
|
|
44
|
+
|
|
45
|
+
```tsx
|
|
93
46
|
import React, { useState } from 'react';
|
|
94
|
-
import { QuizPlayer
|
|
47
|
+
import { QuizPlayer } from '@thanh01pmt/interactive-quiz-kit/react-ui';
|
|
48
|
+
import type { QuizConfig, QuizResult } from '@thanh01pmt/interactive-quiz-kit';
|
|
95
49
|
|
|
96
|
-
//
|
|
50
|
+
// 1. Define or load your quiz configuration
|
|
97
51
|
const myQuiz: QuizConfig = {
|
|
98
|
-
id: "my-
|
|
99
|
-
title: "
|
|
100
|
-
questions: [ /* ...
|
|
101
|
-
settings: {
|
|
52
|
+
id: "my-first-quiz",
|
|
53
|
+
title: "React Basics Quiz",
|
|
54
|
+
questions: [ /* ... array of question objects ... */ ],
|
|
55
|
+
settings: {
|
|
56
|
+
shuffleQuestions: true,
|
|
57
|
+
timeLimitMinutes: 15
|
|
58
|
+
}
|
|
102
59
|
};
|
|
103
60
|
|
|
104
|
-
const
|
|
105
|
-
const
|
|
106
|
-
|
|
107
|
-
const handleQuizComplete = (result: QuizResultType) => {
|
|
61
|
+
const MyQuizPage = () => {
|
|
62
|
+
const handleQuizComplete = (result: QuizResult) => {
|
|
108
63
|
console.log("Quiz Complete!", result);
|
|
109
|
-
|
|
110
|
-
// Xử lý kết quả (ví dụ: hiển thị, gửi lên server)
|
|
111
|
-
};
|
|
112
|
-
|
|
113
|
-
const handleExitQuiz = () => {
|
|
114
|
-
console.log("Exiting quiz");
|
|
115
|
-
// Điều hướng người dùng hoặc làm mới trạng thái
|
|
64
|
+
// Send result to your backend, or display a summary
|
|
116
65
|
};
|
|
117
66
|
|
|
118
67
|
return (
|
|
119
|
-
<
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
68
|
+
<div className="container">
|
|
69
|
+
<QuizPlayer
|
|
70
|
+
quizConfig={myQuiz}
|
|
71
|
+
onQuizComplete={handleQuizComplete}
|
|
72
|
+
/>
|
|
73
|
+
</div>
|
|
124
74
|
);
|
|
125
75
|
};
|
|
76
|
+
```
|
|
126
77
|
|
|
127
|
-
|
|
128
|
-
\`\`\`
|
|
78
|
+
#### Example: Using the `<QuizAuthoringTool>`
|
|
129
79
|
|
|
130
|
-
|
|
131
|
-
\`\`\`tsx
|
|
132
|
-
import React, { useState } from 'react';
|
|
133
|
-
import { QuizAuthoringTool, QuizConfig, emptyQuiz } from 'interactive-quiz-kit';
|
|
80
|
+
Embed the complete authoring experience to allow users to create and edit quizzes.
|
|
134
81
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
82
|
+
```tsx
|
|
83
|
+
import React from 'react';
|
|
84
|
+
import { QuizAuthoringTool, emptyQuiz } from '@thanh01pmt/interactive-quiz-kit/react-ui';
|
|
85
|
+
import type { QuizConfig } from '@thanh01pmt/interactive-quiz-kit';
|
|
138
86
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
87
|
+
const MyAuthoringPage = () => {
|
|
88
|
+
const handleSave = (quiz: QuizConfig) => {
|
|
89
|
+
console.log("Quiz saved:", quiz);
|
|
90
|
+
// Persist the quiz config (e.g., to a database or localStorage)
|
|
142
91
|
};
|
|
143
92
|
|
|
144
|
-
|
|
145
|
-
console.log("Exiting authoring tool");
|
|
146
|
-
// Điều hướng người dùng
|
|
147
|
-
};
|
|
148
|
-
|
|
93
|
+
// Start with an empty quiz template for creation
|
|
149
94
|
return (
|
|
150
95
|
<QuizAuthoringTool
|
|
151
|
-
initialQuizConfig={
|
|
152
|
-
onSaveQuiz={
|
|
153
|
-
onExitAuthoring={handleExitAuthoring} // Tùy chọn
|
|
96
|
+
initialQuizConfig={emptyQuiz}
|
|
97
|
+
onSaveQuiz={handleSave}
|
|
154
98
|
/>
|
|
155
99
|
);
|
|
156
100
|
};
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### 2. Headless Mode (Core Logic Only)
|
|
104
|
+
|
|
105
|
+
Use the library's services, types, and AI flows in any JavaScript/TypeScript environment (e.g., Node.js backend, other frontend frameworks, scripts).
|
|
106
|
+
|
|
107
|
+
> For detailed examples and a full component list, see [**HEADLESS.md**](./HEADLESS.md).
|
|
108
|
+
|
|
109
|
+
#### Example: Creating a Quiz Programmatically with `QuizEditorService`
|
|
110
|
+
|
|
111
|
+
This service allows you to safely manipulate a `QuizConfig` object.
|
|
112
|
+
|
|
113
|
+
```typescript
|
|
114
|
+
import { QuizEditorService, emptyQuiz } from '@thanh01pmt/interactive-quiz-kit';
|
|
115
|
+
import type { MultipleChoiceQuestion } from '@thanh01pmt/interactive-quiz-kit';
|
|
116
|
+
|
|
117
|
+
// Start with an empty quiz config
|
|
118
|
+
const editor = new QuizEditorService(emptyQuiz);
|
|
119
|
+
|
|
120
|
+
// Create a question template
|
|
121
|
+
const mcqTemplate = QuizEditorService.createNewQuestionTemplate('multiple_choice') as MultipleChoiceQuestion;
|
|
122
|
+
|
|
123
|
+
// Populate the question details
|
|
124
|
+
mcqTemplate.prompt = "What is the capital of France?";
|
|
125
|
+
mcqTemplate.options = [
|
|
126
|
+
{ id: 'opt1', text: 'Berlin' },
|
|
127
|
+
{ id: 'opt2', text: 'Paris' },
|
|
128
|
+
{ id: 'opt3', text: 'Madrid' },
|
|
129
|
+
];
|
|
130
|
+
mcqTemplate.correctAnswerId = 'opt2';
|
|
131
|
+
|
|
132
|
+
// Add the question to the quiz
|
|
133
|
+
editor.addQuestion(mcqTemplate);
|
|
134
|
+
|
|
135
|
+
// Get the final, updated quiz configuration
|
|
136
|
+
const finalQuizConfig = editor.getQuiz();
|
|
137
|
+
|
|
138
|
+
// Now you can save `finalQuizConfig` to your database
|
|
139
|
+
console.log(finalQuizConfig);
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
#### Example: Running a Quiz Session with `QuizEngine`
|
|
143
|
+
|
|
144
|
+
This is useful for backend-driven quizzes or for running simulations.
|
|
145
|
+
|
|
146
|
+
```typescript
|
|
147
|
+
import { QuizEngine } from '@thanh01pmt/interactive-quiz-kit';
|
|
148
|
+
import type { QuizConfig, QuizResult } from '@thanh01pmt/interactive-quiz-kit';
|
|
149
|
+
|
|
150
|
+
const myQuizConfig: QuizConfig = /* ... load your quiz config ... */;
|
|
151
|
+
|
|
152
|
+
const engine = new QuizEngine({
|
|
153
|
+
config: myQuizConfig,
|
|
154
|
+
callbacks: {
|
|
155
|
+
onQuizFinish: (result: QuizResult) => {
|
|
156
|
+
console.log(`Quiz finished! Final score: ${result.score}`);
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
});
|
|
160
|
+
|
|
161
|
+
// Simulate answering the first question
|
|
162
|
+
const firstQuestion = engine.getCurrentQuestion();
|
|
163
|
+
if (firstQuestion) {
|
|
164
|
+
engine.submitAnswer(firstQuestion.id, 'id_of_the_user_answer');
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
// Finalize the quiz
|
|
168
|
+
engine.calculateResults();
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
#### Example: Generating a Question with AI
|
|
172
|
+
|
|
173
|
+
Leverage Google Gemini to create quiz content on the fly. *Requires Genkit environment setup.*
|
|
174
|
+
|
|
175
|
+
```typescript
|
|
176
|
+
import { generateTrueFalseQuestion } from '@thanh01pmt/interactive-quiz-kit/ai';
|
|
177
|
+
|
|
178
|
+
async function createNewQuestion() {
|
|
179
|
+
try {
|
|
180
|
+
const { question } = await generateTrueFalseQuestion({
|
|
181
|
+
topic: "The history of the internet",
|
|
182
|
+
difficulty: "medium"
|
|
183
|
+
});
|
|
184
|
+
|
|
185
|
+
if (question) {
|
|
186
|
+
console.log("AI-generated question:", question);
|
|
187
|
+
// Save to your database
|
|
188
|
+
}
|
|
189
|
+
} catch (error) {
|
|
190
|
+
console.error("Failed to generate question:", error);
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
## Supported Question Types
|
|
157
196
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
-
|
|
163
|
-
-
|
|
164
|
-
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
##
|
|
173
|
-
|
|
174
|
-
*
|
|
175
|
-
* **
|
|
176
|
-
* **
|
|
197
|
+
The library supports a wide array of 12+ question types, including:
|
|
198
|
+
- `multiple_choice`
|
|
199
|
+
- `multiple_response`
|
|
200
|
+
- `true_false`
|
|
201
|
+
- `short_answer`
|
|
202
|
+
- `numeric`
|
|
203
|
+
- `fill_in_the_blanks`
|
|
204
|
+
- `sequence`
|
|
205
|
+
- `matching`
|
|
206
|
+
- `drag_and_drop`
|
|
207
|
+
- `hotspot`
|
|
208
|
+
- `blockly_programming`
|
|
209
|
+
- `scratch_programming`
|
|
210
|
+
|
|
211
|
+
## Known Issues
|
|
212
|
+
|
|
213
|
+
* **Blockly/Scratch Integration**: Requires manual copying of assets (`js`, `css`, `media`) from the `blockly` or `scratch-blocks` packages into your project's `public` folder for the UI components to render correctly.
|
|
214
|
+
* **SCORM Packaging**: The `exportQuizAsSCORMZip` function generates a nearly complete package. However, you **must manually** add the library's JavaScript bundle and any necessary CSS (like for Blockly) to the ZIP archive for it to function in an LMS.
|
|
215
|
+
* **AI Generation Limits**: AI generation is not yet supported for `Drag and Drop`, `Hotspot`, `Blockly`, or `Scratch` question types due to their complexity.
|
|
216
|
+
|
|
217
|
+
## 🤝 Contributing
|
|
218
|
+
|
|
219
|
+
Contributions are welcome! Please feel free to submit a pull request or open an issue if you have ideas for improvements or find a bug.
|
|
220
|
+
|
|
221
|
+
1. Fork the repository.
|
|
222
|
+
2. Create your feature branch (`git checkout -b feature/AmazingFeature`).
|
|
223
|
+
3. Commit your changes (`git commit -m 'feat: Add some AmazingFeature'`).
|
|
224
|
+
4. Push to the branch (`git push origin feature/AmazingFeature`).
|
|
225
|
+
5. Open a Pull Request.
|
|
226
|
+
|
|
227
|
+
## 📄 License
|
|
228
|
+
|
|
229
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
package/package.json
CHANGED