payload-quiz-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,35 @@
+Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)
+
+Copyright (c) 2024 Alexandr Studio
+
+You are free to:
+- Share — copy and redistribute the material in any medium or format
+- Adapt — remix, transform, and build upon the material
+
+Under the following terms:
+
+1. Attribution — You must give appropriate credit to "Alexandr Studio", provide a
+   link to the license, and indicate if changes were made. You may do so in any
+   reasonable manner, but not in any way that suggests the licensor endorses you
+   or your use.
+
+2. NonCommercial — You may not use the material for commercial purposes. You may
+   not sell this software or include it in a product or service that you sell.
+
+3. ShareAlike — If you remix, transform, or build upon the material, you must
+   distribute your contributions under the same license as the original.
+
+4. No additional restrictions — You may not apply legal terms or technological
+   measures that legally restrict others from doing anything the license permits.
+
+DISCLAIMER:
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Full license text: https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode

package/README.md

@@ -0,0 +1,413 @@
+# Payload Quiz Plugin
+
+A comprehensive quiz and test system plugin for [Payload CMS](https://payloadcms.com) v3. Create timed quizzes with multiple choice questions, automatic grading, and detailed results.
+
+## Features
+
+- **Collections**: Questions, Tests, and Certificate Types
+- **Multiple Choice Support**: Single or multiple correct answers per question
+- **Timed Tests**: Configurable time limits with automatic submission
+- **Results Tracking**: Detailed results with question-by-question review
+- **i18n Support**: Built-in English and German translations, easily extendable
+- **Customizable**: Override collections, add custom fields, and configure features
+- **React Components**: Ready-to-use Quiz UI components for the frontend
+- **SEO Ready**: Built-in SEO fields for tests using @payloadcms/plugin-seo
+
+## Installation
+
+```bash
+npm install payload-quiz-plugin
+# or
+pnpm add payload-quiz-plugin
+# or
+yarn add payload-quiz-plugin
+```
+
+### Peer Dependencies
+
+This plugin requires the following peer dependencies:
+
+```bash
+npm install payload @payloadcms/richtext-lexical
+```
+
+Optional (for SEO fields):
+```bash
+npm install @payloadcms/plugin-seo
+```
+
+## Quick Start
+
+### 1. Add the Plugin to Payload Config
+
+```typescript
+// payload.config.ts
+import { buildConfig } from 'payload'
+import { quizPlugin } from 'payload-quiz-plugin'
+
+export default buildConfig({
+  // ... your config
+  plugins: [
+    quizPlugin({
+      i18n: {
+        enabled: true,
+        defaultLocale: 'en',
+      },
+      admin: {
+        group: 'Quiz', // Admin panel group name
+      },
+    }),
+  ],
+})
+```
+
+### 2. Create Quiz UI Components
+
+```tsx
+// app/tests/[slug]/page.tsx
+import { getPayload } from 'payload'
+import { QuizClient } from './QuizClient'
+
+export default async function TestPage({ params }) {
+  const payload = await getPayload({ config: configPromise })
+
+  const test = await payload.findByID({
+    collection: 'tests',
+    id: params.slug,
+  })
+
+  const questions = await payload.find({
+    collection: 'questions',
+    where: {
+      certificateTypes: {
+        contains: test.certificateType,
+      },
+    },
+  })
+
+  return <QuizClient test={test} questions={questions.docs} />
+}
+```
+
+```tsx
+// app/tests/[slug]/QuizClient.tsx
+'use client'
+
+import {
+  QuizProvider,
+  useQuiz,
+  QuizTimer,
+  QuizProgress,
+  QuestionCard,
+  QuizResults,
+} from 'payload-quiz-plugin/client'
+
+export function QuizClient({ test, questions }) {
+  return (
+    <QuizProvider questions={questions} timeLimit={test.timeLimit}>
+      <QuizContent test={test} />
+    </QuizProvider>
+  )
+}
+
+function QuizContent({ test }) {
+  const {
+    state,
+    currentQuestion,
+    selectAnswer,
+    deselectAnswer,
+    nextQuestion,
+    prevQuestion,
+    finishQuiz,
+    calculateResults,
+  } = useQuiz()
+
+  // Render your quiz UI using these hooks and components
+  return (
+    <div>
+      <QuizTimer timeRemaining={state.timeRemaining} />
+      <QuizProgress
+        currentIndex={state.currentQuestionIndex}
+        totalQuestions={state.questions.length}
+      />
+      {currentQuestion && (
+        <QuestionCard
+          question={currentQuestion}
+          selectedChoiceIds={state.answers.get(currentQuestion.id) || []}
+          onSelectChoice={selectAnswer}
+          onDeselectChoice={deselectAnswer}
+        />
+      )}
+    </div>
+  )
+}
+```
+
+## Configuration
+
+### Plugin Options
+
+```typescript
+interface QuizPluginConfig {
+  i18n?: {
+    /** Enable i18n support (default: true) */
+    enabled?: boolean
+    /** Default locale (default: 'en') */
+    defaultLocale?: string
+    /** Custom translations */
+    translations?: Record<string, QuizTranslations>
+  }
+
+  collections?: {
+    /** Override Questions collection config */
+    questions?: Partial<CollectionConfig>
+    /** Override Tests collection config */
+    tests?: Partial<CollectionConfig>
+    /** Override CertificateTypes collection config */
+    certificateTypes?: Partial<CollectionConfig>
+  }
+
+  admin?: {
+    /** Admin panel group name (default: 'Quiz') */
+    group?: string
+  }
+
+  features?: {
+    /** Enable certificate types (default: true) */
+    certificateTypes?: boolean
+    /** Enable tests archive block (default: true) */
+    testsArchiveBlock?: boolean
+  }
+}
+```
+
+### Custom Translations
+
+Add your own translations or override existing ones:
+
+```typescript
+quizPlugin({
+  i18n: {
+    enabled: true,
+    translations: {
+      fr: {
+        tests: {
+          title: 'Tests',
+          startButton: 'Commencer le test',
+          finishButton: 'Terminer',
+          // ... more translations
+        },
+        results: {
+          congratulations: 'Félicitations !',
+          // ... more translations
+        },
+      },
+    },
+  },
+})
+```
+
+### Collection Overrides
+
+Customize the collections with additional fields or settings:
+
+```typescript
+quizPlugin({
+  collections: {
+    questions: {
+      access: {
+        read: () => true,
+        create: ({ req }) => req.user?.role === 'admin',
+      },
+      fields: [
+        // Additional fields
+        {
+          name: 'difficulty',
+          type: 'select',
+          options: ['easy', 'medium', 'hard'],
+        },
+      ],
+    },
+  },
+})
+```
+
+## Collections
+
+### Questions
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `question` | textarea | The question text (localized) |
+| `certificateTypes` | relationship | Certificate types this question belongs to |
+| `requiredAnswers` | number | Number of correct answers to select (1 for single choice) |
+| `choices` | array | Answer choices with text, isCorrect flag, and optional explanation |
+| `explanation` | richText | General explanation shown after answering |
+
+### Tests
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | text | Test name (localized) |
+| `certificateType` | relationship | Certificate type for question filtering |
+| `questionCount` | number | Number of questions to include |
+| `timeLimit` | number | Time limit in minutes |
+| `passMark` | number | Percentage required to pass |
+| `allowGoBack` | checkbox | Allow revisiting previous questions |
+| `requireAllAnswered` | checkbox | Require all questions before submitting |
+| `description` | richText | Test description (localized) |
+| `instructions` | richText | Test instructions (localized) |
+| `meta` | group | SEO fields (title, description, image) |
+
+### Certificate Types
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | text | Full certificate name (localized) |
+| `shortName` | text | Abbreviated name (e.g., "PSM-I") |
+| `description` | textarea | Brief description |
+| `slug` | text | URL-friendly identifier |
+
+## Components
+
+### Server-Side Imports
+
+```typescript
+// For payload.config.ts and server components
+import {
+  quizPlugin,
+  getQuizPluginConfig,
+  createQuestionsCollection,
+  createTestsCollection,
+  createCertificateTypesCollection,
+  TestsArchiveBlock,
+  createTestsArchiveBlock,
+  createTranslator,
+  getTranslations,
+} from 'payload-quiz-plugin'
+```
+
+### Client-Side Imports
+
+**IMPORTANT**: All React components with hooks must be imported from `payload-quiz-plugin/client` to ensure proper `"use client"` directive handling.
+
+```typescript
+// For client components only - do NOT import these from 'payload-quiz-plugin'
+import {
+  QuizProvider,
+  useQuiz,
+  QuizTimer,
+  QuizProgress,
+  QuestionCard,
+  ChoiceOption,
+  QuizResults,
+  TestCard,
+  cn, // Tailwind class merge utility
+} from 'payload-quiz-plugin/client'
+```
+
+### QuizProvider
+
+Wraps your quiz UI and manages state:
+
+```tsx
+<QuizProvider questions={questions} timeLimit={30}>
+  {children}
+</QuizProvider>
+```
+
+### useQuiz Hook
+
+Access quiz state and actions:
+
+```typescript
+const {
+  state,           // Current quiz state
+  currentQuestion, // Current question object
+  isFirstQuestion, // Boolean
+  isLastQuestion,  // Boolean
+  answeredCount,   // Number of answered questions
+  selectAnswer,    // (choiceId: string) => void
+  deselectAnswer,  // (choiceId: string) => void
+  nextQuestion,    // () => void
+  prevQuestion,    // () => void
+  goToQuestion,    // (index: number) => void
+  finishQuiz,      // () => void
+  calculateResults, // (passMark: number) => QuizResult
+} = useQuiz()
+```
+
+### TestCard
+
+Display a test card with optional custom media component:
+
+```tsx
+<TestCard
+  doc={test}
+  className="h-full"
+  MediaComponent={({ resource, size }) => (
+    <YourMediaComponent resource={resource} size={size} />
+  )}
+/>
+```
+
+## Blocks
+
+### TestsArchiveBlock
+
+A Payload block for displaying a grid of tests:
+
+```typescript
+// In your page collection
+import { TestsArchiveBlock } from 'payload-quiz-plugin'
+
+export const Pages = {
+  slug: 'pages',
+  fields: [
+    {
+      name: 'layout',
+      type: 'blocks',
+      blocks: [
+        TestsArchiveBlock,
+        // ... other blocks
+      ],
+    },
+  ],
+}
+```
+
+## Styling
+
+The components use Tailwind CSS classes and are designed to work with shadcn/ui-style theming. They use CSS variables like:
+
+- `--background`, `--foreground`
+- `--card`, `--card-foreground`
+- `--primary`, `--primary-foreground`
+- `--muted`, `--muted-foreground`
+- `--border`
+
+Make sure your project has these CSS variables defined.
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  QuizPluginConfig,
+  QuizQuestion,
+  QuizTest,
+  QuizResult,
+  QuestionResult,
+  QuizChoice,
+  TestCardData,
+} from 'payload-quiz-plugin'
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.