@thanh01.pmt/interactive-quiz-kit 1.0.12 → 1.0.15

package/README.md

@@ -1,6 +1,6 @@
 # Interactive Quiz Kit
 
-[![NPM version](https://img.shields.io/npm/v/@thanh01pmt/interactive-quiz-kit.svg)](https://www.npmjs.com/package/@thanh01pmt/interactive-quiz-kit)
+[![NPM version](https://img.shields.io/npm/v/@thanh01.pmt/interactive-quiz-kit.svg)](https://www.npmjs.com/package/@thanh01.pmt/interactive-quiz-kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 **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.
@@ -9,43 +9,51 @@ The library is architected for easy extension and integration, featuring a power
 
 ## ✨ Features
 
-*   **Robust Core Engine**: Handles state management, navigation, automatic grading, and time tracking.
-*   **Rich Question Support**: Includes 12+ question types, from Multiple Choice to complex ones like Blockly/Scratch Programming and Hotspot.
-*   **React-based UI Kit**: A full suite of components to build quiz players and authoring tools.
-    *   `<QuizPlayer>`: The main component for taking quizzes.
-    *   `<QuizAuthoringTool>`: A powerful interface for creating and editing quizzes.
-*   **Headless Mode**: Use all core logic, services, and AI flows independently of the React UI. Ideal for backend integrations, custom frontends, or automation scripts.
-*   **AI-Powered Generation**:
-    *   Generate individual questions based on topic, context, and difficulty.
-    *   Generate entire, well-structured quizzes using a two-stage planning and generation process.
-*   **SCORM & Webhook Integration**:
-    *   Package quizzes as SCORM 1.2 or 2004 compliant ZIP files.
-    *   Send detailed quiz results to a specified webhook URL.
+* **Robust Core Engine**: Handles state management, navigation, automatic grading, and time tracking.
+* **Rich Question Support**: Includes 12+ question types, from Multiple Choice to complex ones like Blockly/Scratch Programming and Hotspot.
+* **Modular React UI Kit**: A full suite of components to build quiz players and authoring tools, organized into logical entry points.
+* **Headless Mode**: Use all core logic, services, and AI flows independently of the React UI. Ideal for backend integrations, custom frontends, or automation scripts.
+* **Advanced AI Capabilities**:
+  * **Single Question Generation**: Create individual questions based on topic, context, and difficulty.
+  * **Full Quiz Generation**: Generate entire, well-structured quizzes using a two-stage planning process.
+  * **AI-Powered Practice Mode**: Generate personalized 10-question quizzes on-the-fly from a user-provided curriculum.
+* **Flexible Content Import**: Import curriculum data and learning objectives from TSV files to power the AI Practice Mode.
+* **SCORM & Webhook Integration**:
+  * Package quizzes as SCORM 1.2 compliant ZIP files.
+  * Send detailed quiz results to a specified webhook URL.
 
 ## 🚀 Installation
 
 ```bash
-npm install @thanh01pmt/interactive-quiz-kit
+npm install @thanh01.pmt/interactive-quiz-kit
 # or
-yarn add @thanh01pmt/interactive-quiz-kit
+yarn add @thanh01.pmt/interactive-quiz-kit
 ```
 
 **Peer Dependencies:** This library requires `react` and `react-dom` as peer dependencies. Ensure they are installed in your project.
 
 ## 📚 Usage
 
-This library supports two primary modes of usage: with the built-in React UI, or in a "headless" mode using only the core logic.
+This library is modular, allowing you to import only the parts you need.
 
-### 1. Standard Mode (with React UI)
+### Understanding the Entry Points
 
-This is the quickest way to get a fully functional quiz application up and running.
+The package is split into several entry points for optimized usage:
 
-#### Example: Displaying a Quiz with `<QuizPlayer>`
+* `@thanh01.pmt/interactive-quiz-kit`: The core "headless" library. Contains all types, services (`QuizEngine`, `QuizEditorService`), and utilities. Use this for backend logic or custom UIs.
+* `@thanh01.pmt/interactive-quiz-kit/react-ui`: General-purpose UI components like `<QuizPlayer>` and `<QuizResult>`.
+* `@thanh01.pmt/interactive-quiz-kit/authoring`: The complete UI suite for creating and editing quizzes, centered around the `<QuizAuthoringTool>` component.
+* `@thanh01.pmt/interactive-quiz-kit/ai`: The headless functions for AI-powered content generation.
+* `@thanh01.pmt/interactive-quiz-kit/player`: A dedicated entry point for the player bundle, useful for SCORM packaging.
+
+### 1. Displaying a Quiz (Player Mode)
+
+Use the `<QuizPlayer>` component for the test-taker's experience.
 
 ```tsx
-import React, { useState } from 'react';
-import { QuizPlayer } from '@thanh01pmt/interactive-quiz-kit/react-ui';
-import type { QuizConfig, QuizResult } from '@thanh01pmt/interactive-quiz-kit';
+import React from 'react';
+import { QuizPlayer } from '@thanh01.pmt/interactive-quiz-kit/react-ui';
+import type { QuizConfig, QuizResultType } from '@thanh01.pmt/interactive-quiz-kit';
 
 // 1. Define or load your quiz configuration
 const myQuiz: QuizConfig = {
@@ -59,7 +67,7 @@ const myQuiz: QuizConfig = {
 };
 
 const MyQuizPage = () => {
-  const handleQuizComplete = (result: QuizResult) => {
+  const handleQuizComplete = (result: QuizResultType) => {
     console.log("Quiz Complete!", result);
     // Send result to your backend, or display a summary
   };
@@ -75,14 +83,15 @@ const MyQuizPage = () => {
 };
 ```
 
-#### Example: Using the `<QuizAuthoringTool>`
+### 2. Creating Quizzes (Authoring Mode)
 
-Embed the complete authoring experience to allow users to create and edit quizzes.
+Use the `<QuizAuthoringTool>` for a complete content creation interface.
 
 ```tsx
 import React from 'react';
-import { QuizAuthoringTool, emptyQuiz } from '@thanh01pmt/interactive-quiz-kit/react-ui';
-import type { QuizConfig } from '@thanh01pmt/interactive-quiz-kit';
+import { QuizAuthoringTool } from '@thanh01.pmt/interactive-quiz-kit/authoring';
+import { emptyQuiz } from '@thanh01.pmt/interactive-quiz-kit';
+import type { QuizConfig } from '@thanh01.pmt/interactive-quiz-kit';
 
 const MyAuthoringPage = () => {
   const handleSave = (quiz: QuizConfig) => {
@@ -100,80 +109,59 @@ const MyAuthoringPage = () => {
 };
 ```
 
-### 2. Headless Mode (Core Logic Only)
+### 3. Using the "Practice with AI" Feature
 
-Use the library's services, types, and AI flows in any JavaScript/TypeScript environment (e.g., Node.js backend, other frontend frameworks, scripts).
+The library includes a complete application flow for AI-powered practice sessions.
 
-> For detailed examples and a full component list, see [**HEADLESS.md**](./HEADLESS.md).
+```tsx
+import React from 'react';
+// AppController is a conceptual component you would build
+// using the blocks provided by the library.
+import { AppController } from './components/AppController'; 
+
+// This component would render the main menu, allowing users to switch
+// between Authoring, Practice Mode, and Managing Topics.
+const FullApplication = () => {
+  return <AppController />;
+};
+```
+
+### 4. Headless Mode (Core Logic Only)
+
+Use the library's services in any JavaScript/TypeScript environment.
 
-#### Example: Creating a Quiz Programmatically with `QuizEditorService`
+> For detailed examples and a full component list, see [**HEADLESS.md**](./HEADLESS.md).
 
-This service allows you to safely manipulate a `QuizConfig` object.
+#### Example: Creating a Quiz Programmatically
 
 ```typescript
-import { QuizEditorService, emptyQuiz } from '@thanh01pmt/interactive-quiz-kit';
-import type { MultipleChoiceQuestion } from '@thanh01pmt/interactive-quiz-kit';
+import { QuizEditorService, emptyQuiz } from '@thanh01.pmt/interactive-quiz-kit';
+import type { MultipleChoiceQuestion } from '@thanh01.pmt/interactive-quiz-kit';
 
 // Start with an empty quiz config
 const editor = new QuizEditorService(emptyQuiz);
 
-// Create a question template
+// Create and populate a question
 const mcqTemplate = QuizEditorService.createNewQuestionTemplate('multiple_choice') as MultipleChoiceQuestion;
-
-// Populate the question details
 mcqTemplate.prompt = "What is the capital of France?";
 mcqTemplate.options = [
   { id: 'opt1', text: 'Berlin' },
   { id: 'opt2', text: 'Paris' },
-  { id: 'opt3', text: 'Madrid' },
 ];
 mcqTemplate.correctAnswerId = 'opt2';
 
-// Add the question to the quiz
 editor.addQuestion(mcqTemplate);
-
-// Get the final, updated quiz configuration
 const finalQuizConfig = editor.getQuiz();
 
-// Now you can save `finalQuizConfig` to your database
 console.log(finalQuizConfig);
 ```
 
-#### Example: Running a Quiz Session with `QuizEngine`
-
-This is useful for backend-driven quizzes or for running simulations.
-
-```typescript
-import { QuizEngine } from '@thanh01pmt/interactive-quiz-kit';
-import type { QuizConfig, QuizResult } from '@thanh01pmt/interactive-quiz-kit';
-
-const myQuizConfig: QuizConfig = /* ... load your quiz config ... */;
-
-const engine = new QuizEngine({
-  config: myQuizConfig,
-  callbacks: {
-    onQuizFinish: (result: QuizResult) => {
-      console.log(`Quiz finished! Final score: ${result.score}`);
-    }
-  }
-});
-
-// Simulate answering the first question
-const firstQuestion = engine.getCurrentQuestion();
-if (firstQuestion) {
-  engine.submitAnswer(firstQuestion.id, 'id_of_the_user_answer');
-}
-
-// Finalize the quiz
-engine.calculateResults();
-```
-
 #### Example: Generating a Question with AI
 
-Leverage Google Gemini to create quiz content on the fly. *Requires Genkit environment setup.*
+*Requires Genkit environment setup.*
 
 ```typescript
-import { generateTrueFalseQuestion } from '@thanh01pmt/interactive-quiz-kit/ai';
+import { generateTrueFalseQuestion } from '@thanh01.pmt/interactive-quiz-kit/ai';
 
 async function createNewQuestion() {
   try {
@@ -184,7 +172,6 @@ async function createNewQuestion() {
 
     if (question) {
       console.log("AI-generated question:", question);
-      // Save to your database
     }
   } catch (error) {
     console.error("Failed to generate question:", error);
@@ -195,35 +182,36 @@ async function createNewQuestion() {
 ## Supported Question Types
 
 The library supports a wide array of 12+ question types, including:
-- `multiple_choice`
-- `multiple_response`
-- `true_false`
-- `short_answer`
-- `numeric`
-- `fill_in_the_blanks`
-- `sequence`
-- `matching`
-- `drag_and_drop`
-- `hotspot`
-- `blockly_programming`
-- `scratch_programming`
+
+* `multiple_choice`
+* `multiple_response`
+* `true_false`
+* `short_answer`
+* `numeric`
+* `fill_in_the_blanks`
+* `sequence`
+* `matching`
+* `drag_and_drop`
+* `hotspot`
+* `blockly_programming`
+* `scratch_programming`
 
 ## Known Issues
 
-*   **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.
-*   **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.
-*   **AI Generation Limits**: AI generation is not yet supported for `Drag and Drop`, `Hotspot`, `Blockly`, or `Scratch` question types due to their complexity.
+* **Asset Integration for Programming Questions**: Using `Blockly` or `Scratch` questions requires manually copying assets (`js`, `css`, `media`) from their respective `node_modules` folders into your project's `public` directory for the UI components to render correctly.
+* **SCORM Packaging**: The SCORM export function relies on fetching the player assets (`player.js`, `styles.css`) from your `public` folder at the time of packaging. Ensure these files are present and accessible.
+* **AI Generation Limits**: AI generation is not yet supported for visually complex types like `Drag and Drop`, `Hotspot`, `Blockly`, or `Scratch`.
 
 ## 🤝 Contributing
 
 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.
 
-1.  Fork the repository.
-2.  Create your feature branch (`git checkout -b feature/AmazingFeature`).
-3.  Commit your changes (`git commit -m 'feat: Add some AmazingFeature'`).
-4.  Push to the branch (`git push origin feature/AmazingFeature`).
-5.  Open a Pull Request.
+1. Fork the repository.
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`).
+3. Commit your changes (`git commit -m 'feat: Add some AmazingFeature'`).
+4. Push to the branch (`git push origin feature/AmazingFeature`).
+5. Open a Pull Request.
 
 ## 📄 License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License.