@quizparts/react 0.0.1

package/dist/hooks/useQuiz.js

@@ -0,0 +1,59 @@
+import { useMemo } from 'react';
+import { useQuizContext } from './useQuizContext.js';
+/**
+ * Quiz-level state and actions. Use inside QuizProvider.
+ * @returns Current question, canSubmit, submitAnswer, goToNextQuestion, score, etc.
+ */
+export const useQuiz = () => {
+    const { session, progress, submitAnswer, goToNextQuestion, goToPreviousQuestion, resetQuiz } = useQuizContext();
+    const currentQuestionIndex = session.currentQuestionIndex;
+    const currentQuestion = session.quiz.questions[currentQuestionIndex] ?? null;
+    const questionCount = session.quiz.questions.length;
+    const canSubmit = useMemo(() => {
+        const q = currentQuestion;
+        const state = session.questionStates[currentQuestionIndex];
+        if (!q || !state)
+            return false;
+        if (state.status === 'correct' || state.status === 'incorrect')
+            return false;
+        if (q.type === 'multiple_choice') {
+            return typeof state.input.selectedChoiceId === 'string' && state.input.selectedChoiceId.length > 0;
+        }
+        if (q.type === 'multi_select') {
+            const ids = state.input.selectedChoiceIds ?? [];
+            return ids.length > 0;
+        }
+        if (q.type === 'text_input') {
+            return typeof state.input.text === 'string' && state.input.text.trim().length > 0;
+        }
+        if (q.type === 'match_pairs') {
+            const pairs = state.input.matchPairs ?? [];
+            return 'pairs' in q && Array.isArray(q.pairs) && pairs.length === q.pairs.length;
+        }
+        if (q.type === 'order_items') {
+            const ordered = state.input.orderedIds ?? [];
+            return 'items' in q && Array.isArray(q.items) && ordered.length === q.items.length;
+        }
+        if (q.type === 'sentence_builder') {
+            const order = state.input.sentenceOrder ?? [];
+            return 'answer' in q && Array.isArray(q.answer) && order.length === q.answer.length;
+        }
+        return false;
+    }, [session, currentQuestionIndex, currentQuestion]);
+    const isComplete = questionCount > 0 && progress.attemptedCount >= questionCount;
+    return {
+        quiz: session.quiz,
+        currentQuestion,
+        currentQuestionIndex,
+        questionCount,
+        canSubmit,
+        isComplete,
+        score: session.score,
+        canGoNext: progress.canGoNext,
+        canGoPrevious: progress.canGoPrevious,
+        goToNextQuestion,
+        goToPreviousQuestion,
+        submitAnswer,
+        resetQuiz,
+    };
+};

package/dist/hooks/useQuizContext.d.ts

@@ -0,0 +1,2 @@
+export declare const useQuizContext: () => import("../index.js").QuizContextValue;
+//# sourceMappingURL=useQuizContext.d.ts.map

package/dist/hooks/useQuizContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQuizContext.d.ts","sourceRoot":"","sources":["../../src/hooks/useQuizContext.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,cAAc,8CAM1B,CAAC"}

package/dist/hooks/useQuizContext.js

@@ -0,0 +1,10 @@
+import { useContext } from 'react';
+import { getQuizContext } from '../context/QuizContext.js';
+const MISSING_PROVIDER = 'Quiz hooks must be used within a QuizProvider. Wrap your app or quiz tree with <QuizProvider quiz={...}>.';
+export const useQuizContext = () => {
+    const ctx = useContext(getQuizContext());
+    if (ctx == null) {
+        throw new Error(MISSING_PROVIDER);
+    }
+    return ctx;
+};

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @quizparts/react – React bindings for the quiz engine.
+ *
+ * Wrap your app (or quiz section) in QuizProvider with a parsed quiz; use QuizRoot, Question,
+ * Prompt, Choices, Choice, SubmitButton, Feedback, Progress, etc. for multiple_choice and
+ * multi_select. Use TextInput for text_input, MatchPairs for match_pairs, OrderList for
+ * order_items, SentenceBuilder for sentence_builder. Hooks: useQuiz, useQuestion, useProgress.
+ */
+export { CORE_VERSION } from '@quizparts/core';
+/** Current React bindings version. */
+export declare const REACT_VERSION = "0.0.1";
+export { QuizProvider, getQuizContext, type QuizContextValue } from './context/QuizContext.js';
+export { useQuizContext } from './hooks/useQuizContext.js';
+export { useQuiz } from './hooks/useQuiz.js';
+export { useQuestion } from './hooks/useQuestion.js';
+export { useProgress } from './hooks/useProgress.js';
+export { QuizRoot } from './components/QuizRoot.js';
+export { Question } from './components/Question.js';
+export { QuestionCard } from './components/QuestionCard.js';
+export { QuestionHeader } from './components/QuestionHeader.js';
+export { QuestionBody } from './components/QuestionBody.js';
+export { QuestionFooter } from './components/QuestionFooter.js';
+export { QuestionInput } from './components/QuestionInput.js';
+export { Prompt } from './components/Prompt.js';
+export { Instruction } from './components/Instruction.js';
+export { ThemeVarsProvider } from './components/ThemeVarsProvider.js';
+export { QuizComplete } from './components/QuizComplete.js';
+export { DefaultQuestionLayout } from './components/DefaultQuestionLayout.js';
+export { QuizFlow } from './components/QuizFlow.js';
+export { DEFAULT_INSTRUCTIONS } from './constants/defaultInstructions.js';
+export { defaultTheme } from '@quizparts/theme';
+export { createQuizFromJson } from '@quizparts/schema';
+export { Hint } from './components/Hint.js';
+export { Choices } from './components/Choices.js';
+export { Choice } from './components/Choice.js';
+export { ChoiceIndicator } from './components/ChoiceIndicator.js';
+export { SubmitButton } from './components/SubmitButton.js';
+export { ContinueButton } from './components/ContinueButton.js';
+export { Feedback } from './components/Feedback.js';
+export { Progress } from './components/Progress.js';
+export { ProgressBar } from './components/ProgressBar.js';
+export { QuestionCounter } from './components/QuestionCounter.js';
+export { TextInput } from './components/TextInput.js';
+export { NextButton } from './components/NextButton.js';
+export { MatchPairs } from './components/MatchPairs.js';
+export { OrderList } from './components/OrderList.js';
+export { SentenceBuilder } from './components/SentenceBuilder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,sCAAsC;AACtC,eAAO,MAAM,aAAa,UAAU,CAAC;AAErC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC/F,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAErD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -0,0 +1,47 @@
+/**
+ * @quizparts/react – React bindings for the quiz engine.
+ *
+ * Wrap your app (or quiz section) in QuizProvider with a parsed quiz; use QuizRoot, Question,
+ * Prompt, Choices, Choice, SubmitButton, Feedback, Progress, etc. for multiple_choice and
+ * multi_select. Use TextInput for text_input, MatchPairs for match_pairs, OrderList for
+ * order_items, SentenceBuilder for sentence_builder. Hooks: useQuiz, useQuestion, useProgress.
+ */
+export { CORE_VERSION } from '@quizparts/core';
+/** Current React bindings version. */
+export const REACT_VERSION = '0.0.1';
+export { QuizProvider, getQuizContext } from './context/QuizContext.js';
+export { useQuizContext } from './hooks/useQuizContext.js';
+export { useQuiz } from './hooks/useQuiz.js';
+export { useQuestion } from './hooks/useQuestion.js';
+export { useProgress } from './hooks/useProgress.js';
+export { QuizRoot } from './components/QuizRoot.js';
+export { Question } from './components/Question.js';
+export { QuestionCard } from './components/QuestionCard.js';
+export { QuestionHeader } from './components/QuestionHeader.js';
+export { QuestionBody } from './components/QuestionBody.js';
+export { QuestionFooter } from './components/QuestionFooter.js';
+export { QuestionInput } from './components/QuestionInput.js';
+export { Prompt } from './components/Prompt.js';
+export { Instruction } from './components/Instruction.js';
+export { ThemeVarsProvider } from './components/ThemeVarsProvider.js';
+export { QuizComplete } from './components/QuizComplete.js';
+export { DefaultQuestionLayout } from './components/DefaultQuestionLayout.js';
+export { QuizFlow } from './components/QuizFlow.js';
+export { DEFAULT_INSTRUCTIONS } from './constants/defaultInstructions.js';
+export { defaultTheme } from '@quizparts/theme';
+export { createQuizFromJson } from '@quizparts/schema';
+export { Hint } from './components/Hint.js';
+export { Choices } from './components/Choices.js';
+export { Choice } from './components/Choice.js';
+export { ChoiceIndicator } from './components/ChoiceIndicator.js';
+export { SubmitButton } from './components/SubmitButton.js';
+export { ContinueButton } from './components/ContinueButton.js';
+export { Feedback } from './components/Feedback.js';
+export { Progress } from './components/Progress.js';
+export { ProgressBar } from './components/ProgressBar.js';
+export { QuestionCounter } from './components/QuestionCounter.js';
+export { TextInput } from './components/TextInput.js';
+export { NextButton } from './components/NextButton.js';
+export { MatchPairs } from './components/MatchPairs.js';
+export { OrderList } from './components/OrderList.js';
+export { SentenceBuilder } from './components/SentenceBuilder.js';

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.tsx"],"names":[],"mappings":""}

package/dist/index.test.js

@@ -0,0 +1,135 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, act, cleanup } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+afterEach(() => cleanup());
+import { parseQuiz } from '@quizparts/schema';
+import { REACT_VERSION, QuizProvider, useQuiz, useProgress, QuizRoot, Question, Prompt, Choices, Choice, SubmitButton, Feedback, Progress, TextInput, NextButton, } from './index.js';
+const quizJson = {
+    id: 'test',
+    title: 'Test Quiz',
+    questions: [
+        {
+            id: 'q1',
+            type: 'multiple_choice',
+            prompt: 'What is 2+2?',
+            choices: [
+                { id: 'a', text: '3' },
+                { id: 'b', text: '4' },
+            ],
+            answer: 'b',
+            explanation: '2+2 equals 4.',
+        },
+        {
+            id: 'q2',
+            type: 'text_input',
+            prompt: 'Say hello',
+            answer: 'hello',
+        },
+    ],
+};
+const parsed = parseQuiz(quizJson);
+const quiz = parsed.success ? parsed.data : { id: '', title: '', questions: [] };
+describe('@quizparts/react', () => {
+    it('exports REACT_VERSION', () => {
+        expect(REACT_VERSION).toBe('0.0.1');
+    });
+    it('throws when useQuiz is used outside QuizProvider', () => {
+        const Throwing = () => {
+            useQuiz();
+            return null;
+        };
+        expect(() => render(_jsx(Throwing, {}))).toThrow(/QuizProvider/);
+    });
+    it('throws when useProgress is used outside QuizProvider', () => {
+        const Throwing = () => {
+            useProgress();
+            return null;
+        };
+        expect(() => render(_jsx(Throwing, {}))).toThrow(/QuizProvider/);
+    });
+    it('Feedback shows nothing before submit', () => {
+        render(_jsx(QuizProvider, { quiz: quiz, children: _jsxs(Question, { children: [_jsx(Prompt, {}), _jsxs(Choices, { children: [_jsx(Choice, { choiceId: "a" }), _jsx(Choice, { choiceId: "b" })] }), _jsx(Feedback, {})] }) }));
+        expect(screen.queryByText('Correct!')).not.toBeInTheDocument();
+        expect(screen.queryByText('Incorrect.')).not.toBeInTheDocument();
+    });
+    it('SubmitButton is disabled when no selection', () => {
+        render(_jsx(QuizProvider, { quiz: quiz, children: _jsxs(Question, { children: [_jsx(Prompt, {}), _jsxs(Choices, { children: [_jsx(Choice, { choiceId: "a" }), _jsx(Choice, { choiceId: "b" })] }), _jsx(SubmitButton, {})] }) }));
+        const submitBtn = screen.getAllByRole('button').find((b) => b.textContent === 'Answer');
+        expect(submitBtn).toBeDisabled();
+    });
+    it('provider and useQuiz expose quiz state', () => {
+        const Reader = () => {
+            const { quiz: q, currentQuestionIndex, questionCount } = useQuiz();
+            return (_jsxs("span", { "data-testid": "info", children: [q.title, " ", currentQuestionIndex + 1, "/", questionCount] }));
+        };
+        render(_jsx(QuizProvider, { quiz: quiz, children: _jsx(Reader, {}) }));
+        expect(screen.getByTestId('info')).toHaveTextContent('Test Quiz 1/2');
+    });
+    it('multiple choice: select and submit', async () => {
+        const user = userEvent.setup();
+        render(_jsx(QuizProvider, { quiz: quiz, children: _jsx(QuizRoot, { children: _jsxs(Question, { children: [_jsx(Prompt, {}), _jsxs(Choices, { children: [_jsx(Choice, { choiceId: "a" }), _jsx(Choice, { choiceId: "b" })] }), _jsx(SubmitButton, {}), _jsx(Feedback, {})] }) }) }));
+        expect(screen.getByText('What is 2+2?')).toBeInTheDocument();
+        const choiceB = document.querySelector('[data-choice-id="b"]');
+        if (choiceB)
+            await act(() => user.click(choiceB));
+        expect(choiceB).toHaveAttribute('data-selected');
+        const submitBtn = screen.getAllByRole('button').find((b) => b.textContent === 'Answer');
+        if (submitBtn)
+            await act(() => user.click(submitBtn));
+        expect(screen.getByText('Correct!')).toBeInTheDocument();
+        expect(screen.getByText('2+2 equals 4.')).toBeInTheDocument();
+    });
+    it('progress updates after submit and next', async () => {
+        const user = userEvent.setup();
+        render(_jsxs(QuizProvider, { quiz: quiz, children: [_jsx(Progress, {}), _jsxs(Question, { children: [_jsx(Prompt, {}), _jsxs(Choices, { children: [_jsx(Choice, { choiceId: "a" }), _jsx(Choice, { choiceId: "b" })] }), _jsx(SubmitButton, {}), _jsx(NextButton, {})] })] }));
+        expect(screen.getByLabelText(/Question 1 of 2/)).toBeInTheDocument();
+        const choiceB = document.querySelector('[data-choice-id="b"]');
+        if (choiceB)
+            await act(() => user.click(choiceB));
+        const submitBtn = screen.getAllByRole('button').find((b) => b.textContent === 'Answer');
+        if (submitBtn)
+            await act(() => user.click(submitBtn));
+        const nextBtn = screen.getByRole('button', { name: 'Next' });
+        await act(() => user.click(nextBtn));
+        expect(screen.getByText('Say hello')).toBeInTheDocument();
+    });
+    it('text input: type and submit', async () => {
+        const user = userEvent.setup();
+        const quizTextOnly = { ...quiz, questions: [quiz.questions[1]] };
+        render(_jsx(QuizProvider, { quiz: quizTextOnly, children: _jsxs(Question, { children: [_jsx(Prompt, {}), _jsx(TextInput, {}), _jsx(SubmitButton, {}), _jsx(Feedback, {})] }) }));
+        const input = screen.getByRole('textbox');
+        await act(() => user.type(input, 'hello'));
+        const submitBtn = screen.getAllByRole('button').find((b) => b.textContent === 'Answer');
+        if (submitBtn)
+            await act(() => user.click(submitBtn));
+        expect(screen.getByText('Correct!')).toBeInTheDocument();
+    });
+    it('useProgress returns current, total, percent', () => {
+        const Reader = () => {
+            const p = useProgress();
+            return (_jsxs("span", { "data-testid": "prog", children: [p.current, "/", p.total, " ", p.percent, "%"] }));
+        };
+        render(_jsx(QuizProvider, { quiz: quiz, children: _jsx(Reader, {}) }));
+        expect(screen.getByTestId('prog')).toHaveTextContent('1/2 0%');
+    });
+    it('resetQuiz restores initial state', async () => {
+        const user = userEvent.setup();
+        const ResetButton = () => {
+            const { resetQuiz: reset } = useQuiz();
+            return _jsx("button", { type: "button", onClick: () => reset(), children: "Reset" });
+        };
+        render(_jsxs(QuizProvider, { quiz: quiz, children: [_jsx(Progress, {}), _jsxs(Question, { children: [_jsx(Prompt, {}), _jsxs(Choices, { children: [_jsx(Choice, { choiceId: "a" }), _jsx(Choice, { choiceId: "b" })] }), _jsx(SubmitButton, {})] }), _jsx(ResetButton, {})] }));
+        const choiceB = document.querySelector('[data-choice-id="b"]');
+        if (!choiceB)
+            throw new Error('Choice b not found');
+        await act(() => user.click(choiceB));
+        const submitBtn = screen.getAllByRole('button').find((b) => b.textContent === 'Answer');
+        if (submitBtn)
+            await act(() => user.click(submitBtn));
+        expect(screen.getByText('Score: 1')).toBeInTheDocument();
+        await act(() => user.click(screen.getByRole('button', { name: 'Reset' })));
+        expect(screen.getByText('Score: 0')).toBeInTheDocument();
+        expect(screen.getByText('What is 2+2?')).toBeInTheDocument();
+    });
+});

package/dist/test/setup.d.ts

@@ -0,0 +1,2 @@
+import '@testing-library/jest-dom/vitest';
+//# sourceMappingURL=setup.d.ts.map

package/dist/test/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/test/setup.ts"],"names":[],"mappings":"AAAA,OAAO,kCAAkC,CAAC"}

package/dist/test/setup.js

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/vitest';

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@quizparts/react",
+  "version": "0.0.1",
+  "description": "React UI for QuizParts (web) — start here. Provider, components, and hooks; includes engine and schema.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ovrpro/QuizParts.git"
+  },
+  "homepage": "https://github.com/ovrpro/QuizParts#readme",
+  "bugs": {
+    "url": "https://github.com/ovrpro/QuizParts/issues"
+  },
+  "keywords": ["quiz", "react", "components", "learning", "headless"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src --ext .ts,.tsx",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@quizparts/core": "0.0.1",
+    "@quizparts/schema": "0.0.1",
+    "@quizparts/theme": "0.0.1"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.0.1",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/react": "^18.3.12",
+    "happy-dom": "^15.11.7",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  }
+}