payload-quiz-plugin 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,434 @@
+import { CollectionConfig, Plugin, Block } from 'payload';
+
+/**
+ * Translation keys for the quiz plugin
+ */
+interface QuizTranslations {
+    tests?: {
+        title?: string;
+        titleSingular?: string;
+        titlePlural?: string;
+        pageTitle?: string;
+        startButton?: string;
+        finishButton?: string;
+        nextButton?: string;
+        previousButton?: string;
+        noQuestionsAvailable?: string;
+        noQuestionsDescription?: string;
+        backToTests?: string;
+        questionsLabel?: string;
+        minutesLabel?: string;
+        passMarkLabel?: string;
+        beginTestDescription?: string;
+        showingRange?: string;
+        showingSingle?: string;
+        noResults?: string;
+    };
+    questions?: {
+        selectOne?: string;
+        selectMultiple?: string;
+        loading?: string;
+    };
+    results?: {
+        congratulations?: string;
+        keepPracticing?: string;
+        youPassed?: string;
+        needToPass?: string;
+        correct?: string;
+        incorrect?: string;
+        unanswered?: string;
+        timeTaken?: string;
+        tryAgain?: string;
+        backToTests?: string;
+        reviewAnswers?: string;
+        question?: string;
+        yourAnswer?: string;
+        correctAnswer?: string;
+        explanation?: string;
+    };
+    timer?: {
+        timeRemaining?: string;
+    };
+    modal?: {
+        unansweredTitle?: string;
+        unansweredDescription?: string;
+        continueTest?: string;
+        finishAnyway?: string;
+    };
+}
+/**
+ * i18n configuration for the quiz plugin
+ */
+interface QuizI18nConfig {
+    /**
+     * Enable i18n support. When false, uses defaultLocale translations only.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Default locale to use when i18n is disabled or as fallback
+     * @default 'en'
+     */
+    defaultLocale?: string;
+    /**
+     * Custom translations that override or extend plugin defaults.
+     * Keys are locale codes (e.g., 'en', 'de', 'fr')
+     */
+    translations?: Record<string, QuizTranslations>;
+}
+/**
+ * Collection customization options
+ */
+interface QuizCollectionOverrides {
+    /**
+     * Override or extend the Questions collection config
+     */
+    questions?: Partial<CollectionConfig>;
+    /**
+     * Override or extend the Tests collection config
+     */
+    tests?: Partial<CollectionConfig>;
+    /**
+     * Override or extend the CertificateTypes collection config
+     */
+    certificateTypes?: Partial<CollectionConfig>;
+}
+/**
+ * Admin UI configuration
+ */
+interface QuizAdminConfig {
+    /**
+     * Admin group name for quiz collections
+     * @default 'Quiz'
+     */
+    group?: string;
+}
+/**
+ * Main plugin configuration
+ */
+interface QuizPluginConfig {
+    /**
+     * i18n configuration
+     */
+    i18n?: QuizI18nConfig;
+    /**
+     * Collection configuration overrides
+     */
+    collections?: QuizCollectionOverrides;
+    /**
+     * Admin panel configuration
+     */
+    admin?: QuizAdminConfig;
+    /**
+     * Enable or disable specific features
+     */
+    features?: {
+        /**
+         * Enable certificate types collection
+         * @default true
+         */
+        certificateTypes?: boolean;
+        /**
+         * Enable the tests archive block
+         * @default true
+         */
+        testsArchiveBlock?: boolean;
+    };
+}
+/**
+ * Resolved plugin configuration with all defaults applied
+ */
+interface ResolvedQuizPluginConfig {
+    i18n: Required<QuizI18nConfig>;
+    collections: QuizCollectionOverrides;
+    admin: Required<QuizAdminConfig>;
+    features: {
+        certificateTypes: boolean;
+        testsArchiveBlock: boolean;
+    };
+}
+
+/**
+ * Quiz Plugin for Payload CMS
+ *
+ * Adds quiz/test functionality with:
+ * - Questions collection with multiple choice support
+ * - Tests collection with configurable settings
+ * - Certificate Types collection for organizing questions
+ * - Quiz UI components for the frontend
+ *
+ * @example
+ * ```ts
+ * import { quizPlugin } from 'payload-quiz-plugin'
+ *
+ * export default buildConfig({
+ *   plugins: [
+ *     quizPlugin({
+ *       i18n: {
+ *         enabled: true,
+ *         translations: {
+ *           fr: { tests: { title: 'Tests' } }
+ *         }
+ *       }
+ *     })
+ *   ]
+ * })
+ * ```
+ */
+declare function quizPlugin(pluginConfig?: QuizPluginConfig): Plugin;
+/**
+ * Get the resolved plugin configuration
+ * Useful for accessing translations and settings in components
+ */
+declare function getQuizPluginConfig(pluginConfig?: QuizPluginConfig): ResolvedQuizPluginConfig;
+
+declare function createCertificateTypesCollection(config: ResolvedQuizPluginConfig): CollectionConfig;
+
+declare function createQuestionsCollection(config: ResolvedQuizPluginConfig): CollectionConfig;
+
+declare function createTestsCollection(config: ResolvedQuizPluginConfig): CollectionConfig;
+
+/**
+ * Quiz Plugin Types
+ * These types are standalone and don't depend on generated payload-types
+ */
+/**
+ * Rich text data structure (Lexical format)
+ */
+type RichTextData = {
+    root: {
+        type: string;
+        children: unknown[];
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+} | null;
+/**
+ * Component for rendering rich text content
+ * This allows projects to provide their own RichText component
+ */
+type RichTextRenderer = React.ComponentType<{
+    data: RichTextData;
+    enableGutter?: boolean;
+    className?: string;
+}>;
+/**
+ * Choice option in a question
+ */
+type QuizChoice = {
+    id?: string | null;
+    text: string;
+    isCorrect?: boolean | null;
+    explanation?: RichTextData;
+};
+/**
+ * Question structure for the quiz
+ */
+type QuizQuestion = {
+    id: number;
+    question: string;
+    requiredAnswers?: number | null;
+    choices?: QuizChoice[] | null;
+    explanation?: RichTextData;
+};
+/**
+ * Test configuration
+ */
+type QuizTest = {
+    id?: number;
+    title: string;
+    slug?: string | null;
+    questionCount?: number | null;
+    timeLimit?: number | null;
+    passMark?: number | null;
+    questionsPerPage?: number | null;
+    allowGoBack?: boolean | null;
+    requireAllAnswered?: boolean | null;
+};
+/**
+ * User's answer to a question
+ */
+type UserAnswer = {
+    questionId: number;
+    selectedChoiceIds: string[];
+};
+/**
+ * Quiz state for the reducer
+ */
+type QuizState = {
+    status: 'loading' | 'ready' | 'in_progress' | 'completed';
+    questions: QuizQuestion[];
+    currentQuestionIndex: number;
+    answers: Map<number, string[]>;
+    startTime: number | null;
+    endTime: number | null;
+    timeRemaining: number;
+};
+/**
+ * Actions for the quiz reducer
+ */
+type QuizAction = {
+    type: 'SET_QUESTIONS';
+    questions: QuizQuestion[];
+} | {
+    type: 'START_QUIZ';
+    timeLimit: number;
+} | {
+    type: 'SELECT_ANSWER';
+    questionId: number;
+    choiceId: string;
+    isMultiple: boolean;
+} | {
+    type: 'DESELECT_ANSWER';
+    questionId: number;
+    choiceId: string;
+} | {
+    type: 'NEXT_QUESTION';
+} | {
+    type: 'PREV_QUESTION';
+} | {
+    type: 'GO_TO_QUESTION';
+    index: number;
+} | {
+    type: 'TICK_TIMER';
+} | {
+    type: 'FINISH_QUIZ';
+};
+/**
+ * Result of the quiz
+ */
+type QuizResult = {
+    totalQuestions: number;
+    correctAnswers: number;
+    incorrectAnswers: number;
+    unanswered: number;
+    score: number;
+    passed: boolean;
+    passMark: number;
+    timeTaken: number;
+    questionResults: QuestionResult[];
+};
+/**
+ * Result for a single question
+ */
+type QuestionResult = {
+    questionId: number;
+    question: string;
+    requiredAnswers: number;
+    isCorrect: boolean;
+    userAnswers: string[];
+    correctAnswers: string[];
+    choices: {
+        id: string;
+        text: string;
+        isCorrect: boolean;
+        wasSelected: boolean;
+        explanation?: RichTextData;
+    }[];
+    explanation?: RichTextData;
+};
+
+/**
+ * Types for TestCard component
+ * These are standalone and don't depend on generated payload-types
+ */
+/**
+ * Media object structure (simplified)
+ */
+type TestCardMedia = {
+    url?: string | null;
+    alt?: string | null;
+    width?: number | null;
+    height?: number | null;
+    [key: string]: unknown;
+};
+/**
+ * Certificate type structure
+ */
+type TestCardCertificateType = {
+    id?: number | string;
+    shortName?: string | null;
+    title?: string | null;
+    [key: string]: unknown;
+};
+/**
+ * Test meta information
+ */
+type TestCardMeta = {
+    title?: string | null;
+    description?: string | null;
+    image?: TestCardMedia | number | string | null;
+};
+/**
+ * Data structure for a test card
+ */
+type TestCardData = {
+    id?: number | string;
+    slug?: string | null;
+    title?: string | null;
+    certificateType?: TestCardCertificateType | number | string | null;
+    meta?: TestCardMeta | null;
+    questionCount?: number | null;
+    timeLimit?: number | null;
+    passMark?: number | null;
+};
+/**
+ * Props for the TestCard component
+ */
+type TestCardProps = {
+    /** Test data to display */
+    doc?: TestCardData;
+    /** Override title */
+    title?: string;
+    /** Additional class names */
+    className?: string;
+    /** Custom media renderer component */
+    MediaComponent?: React.ComponentType<{
+        resource: TestCardMedia;
+        size?: string;
+        fill?: boolean;
+        pictureClassName?: string;
+        imgClassName?: string;
+    }>;
+};
+
+/**
+ * Create a translation function for a specific locale
+ */
+declare function createTranslator(config: ResolvedQuizPluginConfig, locale?: string): (key: string, params?: Record<string, string | number>, fallback?: string) => string;
+/**
+ * Get all merged translations for a locale (useful for passing to client components)
+ */
+declare function getTranslations(config: ResolvedQuizPluginConfig, locale?: string): QuizTranslations;
+/**
+ * Check if a locale has translations available
+ */
+declare function hasLocale(config: ResolvedQuizPluginConfig, locale: string): boolean;
+/**
+ * Get all available locales
+ */
+declare function getAvailableLocales(config: ResolvedQuizPluginConfig): string[];
+
+type TestsArchiveBlockConfig = {
+    /** Override the block slug */
+    slug?: string;
+    /** Override labels */
+    labels?: {
+        singular?: string;
+        plural?: string;
+    };
+    /** Additional fields to add to the block */
+    additionalFields?: Block['fields'];
+};
+/**
+ * Creates the TestsArchiveBlock configuration
+ * This block allows displaying a grid of tests filtered by certificate type
+ */
+declare function createTestsArchiveBlock(pluginConfig: ResolvedQuizPluginConfig, blockConfig?: TestsArchiveBlockConfig): Block;
+/**
+ * Default TestsArchive block for quick setup
+ * Uses default plugin configuration
+ */
+declare const TestsArchiveBlock: Block;
+
+export { type QuestionResult, type QuizAction, type QuizAdminConfig, type QuizChoice, type QuizCollectionOverrides, type QuizI18nConfig, type QuizPluginConfig, type QuizQuestion, type QuizResult, type QuizState, type QuizTest, type QuizTranslations, type ResolvedQuizPluginConfig, type RichTextData, type RichTextRenderer, type TestCardCertificateType, type TestCardData, type TestCardMedia, type TestCardMeta, type TestCardProps, TestsArchiveBlock, type TestsArchiveBlockConfig, type UserAnswer, createCertificateTypesCollection, createQuestionsCollection, createTestsArchiveBlock, createTestsCollection, createTranslator, getAvailableLocales, getQuizPluginConfig, getTranslations, hasLocale, quizPlugin };