@thanh01.pmt/interactive-quiz-kit
v1.4.11
Published
A comprehensive library for creating, managing, and playing interactive quizzes, with AI generation and SCORM support.
Maintainers
Readme
Interactive Quiz Kit
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.
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.
✨ Features
- Robust Core Engine: Handles state management, navigation, automatic grading, and time tracking.
- 3D Instructional Design Cube (v1.3.0):
- 3D Pedagogy Coordinates: Every question maps onto a 3D coordinate space comprising Cognitive Process (Bloom's 6 levels), Knowledge Dimension (4 types: Factual, Conceptual, Procedural, Metacognitive), and Depth of Knowledge (Webb's DOK 1–4).
- Concept-Centric Question IDs: Generates deterministic, traceable identifiers (
CONCEPT-HASH-RANDOM) tied directly to the Curriculum Knowledge Graph. - Hess Cognitive Rigor Matrix Heatmap: Interactive $6 \times 4$ heatmap grid (
<HessCognitiveRigorGrid />) visualizing learner mastery across Bloom $\times$ DOK with drill-down review.
- 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, diagnostic dashboards, and authoring tools. Enterprise-compliant design with SVG/Lucide icons (strictly no emojis in UI).
- Headless Mode: Use all core logic, services, and AI flows independently of the React UI. Ideal for backend integrations, custom frontends, or automation scripts.
- 9+ Academic Rigor AI Generation:
- Single & Multi Question Generation: Generate high-standard, pedogogically-sound questions with realistic distractor rationales and clear conceptual explanations across all 9 supported AI types.
- LLM-as-Judge Validated: Benchmarked and evaluated via automated pedagogical judges against CSTA, ACM/IEEE, and Anderson & Krathwohl standards.
- 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
npm install @thanh01.pmt/interactive-quiz-kit
# or
yarn add @thanh01.pmt/interactive-quiz-kitPeer Dependencies: This library requires react and react-dom as peer dependencies. Ensure they are installed in your project.
📚 Usage
This library is modular, allowing you to import only the parts you need.
Understanding the Entry Points
The package is split into several entry points for optimized usage:
@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.
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 = {
id: "my-first-quiz",
title: "React Basics Quiz",
questions: [ /* ... array of question objects ... */ ],
settings: {
shuffleQuestions: true,
timeLimitMinutes: 15
}
};
const MyQuizPage = () => {
const handleQuizComplete = (result: QuizResultType) => {
console.log("Quiz Complete!", result);
// Send result to your backend, or display a summary
};
return (
<div className="container">
<QuizPlayer
quizConfig={myQuiz}
onQuizComplete={handleQuizComplete}
/>
</div>
);
};2. Creating Quizzes (Authoring Mode)
Use the <QuizAuthoringTool> for a complete content creation interface.
import React from 'react';
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) => {
console.log("Quiz saved:", quiz);
// Persist the quiz config (e.g., to a database or localStorage)
};
// Start with an empty quiz template for creation
return (
<QuizAuthoringTool
initialQuizConfig={emptyQuiz}
onSaveQuiz={handleSave}
/>
);
};3. Using the "Practice with AI" Feature
The library includes a complete application flow for AI-powered practice sessions.
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.
For detailed examples and a full component list, see HEADLESS.md.
Example: Creating a Quiz Programmatically
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 and populate a question
const mcqTemplate = QuizEditorService.createNewQuestionTemplate('multiple_choice') as MultipleChoiceQuestion;
mcqTemplate.prompt = "What is the capital of France?";
mcqTemplate.options = [
{ id: 'opt1', text: 'Berlin' },
{ id: 'opt2', text: 'Paris' },
];
mcqTemplate.correctAnswerId = 'opt2';
editor.addQuestion(mcqTemplate);
const finalQuizConfig = editor.getQuiz();
console.log(finalQuizConfig);Example: Generating a Question with AI
Requires Genkit environment setup.
import { generateTrueFalseQuestion } from '@thanh01.pmt/interactive-quiz-kit/ai';
async function createNewQuestion() {
try {
const { question } = await generateTrueFalseQuestion({
topic: "The history of the internet",
difficulty: "Medium"
});
if (question) {
console.log("AI-generated question:", question);
}
} catch (error) {
console.error("Failed to generate question:", error);
}
}3D Instructional Design Cube & Hess Cognitive Rigor Matrix
Starting in v1.3.0, Interactive Quiz Kit integrates an educational 3D coordinate model:
- X-Axis — Cognitive Process (Revised Bloom's Taxonomy):
REMEMBER|UNDERSTAND|APPLY|ANALYZE|EVALUATE|CREATE
- Y-Axis — Knowledge Dimension (Anderson & Krathwohl):
FACTUAL|CONCEPTUAL|PROCEDURAL|METACOGNITIVE
- Z-Axis — Depth of Knowledge (Webb's DOK):
DOK1_RECALL|DOK2_SKILL_CONCEPT|DOK3_STRATEGIC_THINKING|DOK4_EXTENDED_THINKING
Visualizing Results with the Hess Matrix
The <HessCognitiveRigorGrid /> component plots quiz results across a $6 \times 4$ heatmap (Bloom vs. DOK) with click-to-inspect drill-downs for every tested coordinate:
import { HessCognitiveRigorGrid } from '@thanh01.pmt/interactive-quiz-kit/react-ui';
function ExamAnalytics({ quizResult }) {
return (
<HessCognitiveRigorGrid
questionResults={quizResult.questionResults}
title="Hess Cognitive Rigor Assessment Grid"
/>
);
}Concept-Centric Question IDs
Questions now follow the deterministic syntax:
[CONCEPT_CODE]-[8_CHAR_PROMPT_HASH]-[4_CHAR_RANDOM]
Example: CON-RECURSION-a1b2c3d4-x9z2This enables direct graph traversal back to Master Knowledge Trees (e.g. ACM/IEEE CS2023 or CSTA frameworks).
Supported Question Types
The library supports a wide array of 12+ question types, including:
multiple_choicemultiple_responsetrue_falseshort_answernumericfill_in_the_blankssequencematchingdrag_and_drophotspotblockly_programmingscratch_programming
Runtime and SCORM assets
The npm package includes the browser player, stylesheet, and the Scratch runtime assets needed by SCORM packages. Consumers can resolve the machine-readable asset list through the exported subpath:
const manifestPath = import.meta.resolve(
"@thanh01.pmt/interactive-quiz-kit/scorm-assets/manifest.json",
);scorm-assets/manifest.json maps package-relative source paths to their target
paths in a hosted asset directory or SCORM ZIP. Build tools should copy every
manifest entry instead of depending on package-manager-specific node_modules
layouts. The existing exportQuizAsSCORMZip convenience API still expects the
assets to be hosted under /static; custom hosts can use the manifest and the
headless SCORM generators to control loading and download behavior.
Known Issues
- AI Generation Limits: AI generation is not yet supported for visually complex types like
Drag and Drop,Hotspot,Blockly, orScratch.
🤝 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.
- Fork the repository.
- Create your feature branch (
git checkout -b feature/AmazingFeature). - Commit your changes (
git commit -m 'feat: Add some AmazingFeature'). - Push to the branch (
git push origin feature/AmazingFeature). - Open a Pull Request.
📄 License
This project is licensed under the MIT License.
