@tinyweb_dev/oe-exam-sdk 0.1.28 → 0.1.29

package/dist/components/exams/take/utils/answer-transformers.js

@@ -1 +1,452 @@
-function n(n){const t=n.match(/-opt-(\d+)$/);return t?parseInt(t[1],10):0}function t(n){return"string"==typeof n&&n.includes("-opt-")}function e(n){return Array.isArray(n)&&n.every(n=>t(n))}function s(n){return"object"==typeof n&&null!==n&&!Array.isArray(n)&&t(n.optionId)}function o(n){return n.startsWith("sq-")||n.includes("-sq-")||n.includes("-blank-")||n.includes("-item-")}function r(n){return/^\d+-\d+$/.test(n)}function i(n){return n.startsWith("label-")}function u(n){return n.startsWith("region-")}function f(n,t){for(const e of t){if("READ_PASSAGE_AND_ANSWER_QUESTIONS"===e.questionType&&e.questions.length>0)return{parentId:e.questions[0].id,questionType:e.questionType};if("CHOOSE_THE_CORRECT_ANSWER_GROUP"===e.questionType){const t=e.questions.find(t=>n.startsWith(`${t.id}-item-`));if(t)return{parentId:t.id,questionType:e.questionType}}}return null}function a(n){for(const t of n)if("FILL_MISSING_WORDS_IN_GRID"===t.questionType&&t.questions.length>0)return{parentId:t.questions[0].id,questionType:t.questionType};return null}function c(n){for(const t of n)if("LABEL_THE_PICTURE"===t.questionType&&t.questions.length>0)return{parentId:t.questions[0].id,questionType:t.questionType};return null}function p(n,t){for(const e of t)if(("READ_AND_COLOR_OBJECTS"===e.questionType||"IMAGE_OBJECT_MATCHING"===e.questionType)&&e.questions.length>0){const t=e.questions[0],s=t.content;if((s?.regions||s?.regionNodes||[]).some(t=>t.id===n))return{parentId:t.id,questionType:e.questionType}}return null}function d(n,t){for(const e of t)if("LOOK_PICTURE_FILL_WORD_HINT"===e.questionType)for(const t of e.questions){if(n.startsWith(`${t.id}-blank-`))return{parentId:t.id,questionType:e.questionType};const s=t.content;if(s?.subQuestions?.some(t=>t.id===n))return{parentId:t.id,questionType:e.questionType}}return null}function q(n,t){for(const e of t)for(const t of e.questions)if(t.id===n)return e.questionType;return null}function I(n,t){return"number"==typeof n||"string"==typeof n?{answer:n}:Array.isArray(n)?"WORD_FILL_PARAGRAPH"===t?{answers:n}:{answer:n}:"object"==typeof n&&null!==n?n:{answer:n}}export function transformAnswersForSubmission(l,y){const T=[],_=new Map,h=new Map,A=new Map,w=new Map,g=new Set;for(const n of y)for(const t of n.questions)"SPEAKING"===t.question_skill_type&&g.add(t.id);for(const[m,O]of Object.entries(l)){if(null==O||""===O)continue;if(g.has(m)&&"string"==typeof O)continue;if(r(m)){const n=a(y);n&&(h.has(n.parentId)||h.set(n.parentId,{}),h.get(n.parentId)[m]=String(O));continue}if(i(m)){const n=c(y);n&&(A.has(n.parentId)||A.set(n.parentId,{}),A.get(n.parentId)[m]=String(O));continue}if(u(m)){const n=p(m,y);n&&(w.has(n.parentId)||w.set(n.parentId,{}),w.get(n.parentId)[m]=String(O));continue}if(o(m)){let e=f(m,y);if(e||(e=d(m,y)),e){_.has(e.parentId)||_.set(e.parentId,{});const s=t(O)?n(O):O;_.get(e.parentId)[m]=s}continue}const l=q(m,y);let S;S=t(O)?I(n(O),l):e(O)?I(O.map(t=>n(t)),l):s(O)?I(n(O.optionId),l):I(O,l),T.push({questionId:m,answer:S})}for(const[n,t]of _){if(Object.keys(t).some(n=>n.includes("-item-"))){const e=y.flatMap(n=>n.questions).find(t=>t.id===n),s=Array.isArray(e?.content?.items)?e.content.items.length:0,o=Array.from({length:s},(e,s)=>{const o=t[`${n}-item-${s}`];return"string"==typeof o?o:""});T.push({questionId:n,answer:{answer:o}});continue}if(Object.keys(t).some(n=>n.includes("-blank-"))){const e=Object.entries(t).sort(([n],[t])=>{const e=n.match(/-blank-(\d+)$/),s=t.match(/-blank-(\d+)$/);return(e?parseInt(e[1],10):0)-(s?parseInt(s[1],10):0)}).map(([,n])=>n).join(", ");T.push({questionId:n,answer:{answer:e}})}else T.push({questionId:n,answer:{subAnswers:t}})}for(const[n,t]of h)T.push({questionId:n,answer:{answers:t}});for(const[n,t]of A)T.push({questionId:n,answer:{answers:t}});for(const[n,t]of w)T.push({questionId:n,answer:{answers:t}});return T}export function getValidQuestionIds(n){const t=new Set;for(const e of n)for(const n of e.questions)t.add(n.id);return t}
+/**
+ * Answer Transformers - Transform frontend answers to API format
+ *
+ * Frontend stores answers with synthetic IDs for UI convenience.
+ * This module transforms them to the format backend expects.
+ *
+ * Backend grading service expects:
+ * - Single choice: { answer: optionIndex } or { optionId: "uuid" }
+ * - Fill blank: { answer: "text" } or { answers: ["text1", "text2"] }
+ * - Matching: { pairs: [{ left: "id1", right: "id2" }] }
+ */
+import { normalizeCrossOutWordGroupAnswer } from './cross-out-word-group.transformer';
+/**
+ * Extract option index from synthetic option ID
+ * e.g., "uuid-opt-2" -> 2
+ */
+function extractOptionIndex(optionId) {
+    const match = optionId.match(/-opt-(\d+)$/);
+    return match ? parseInt(match[1], 10) : 0;
+}
+/**
+ * Check if answer is a synthetic option ID (contains -opt-)
+ */
+function isSyntheticOptionId(answer) {
+    return typeof answer === 'string' && answer.includes('-opt-');
+}
+function isSyntheticOptionIdArray(answer) {
+    return Array.isArray(answer) && answer.every((item) => isSyntheticOptionId(item));
+}
+/**
+ * Check if answer is an object carrying a synthetic option ID, e.g.
+ * { optionId: "uuid-opt-2" } produced by the English Certification (TOEIC)
+ * single-choice renderer. These must be converted to { answer: index } so the
+ * backend (which grades by index) can match them. Real backend option UUIDs
+ * (no "-opt-N" suffix) are left untouched — backend grades those by optionId.
+ */
+function isAnswerObjectWithSyntheticOptionId(answer) {
+    return (typeof answer === 'object' &&
+        answer !== null &&
+        !Array.isArray(answer) &&
+        isSyntheticOptionId(answer.optionId));
+}
+/**
+ * Check if questionId is a synthetic sub-question ID
+ * e.g., "sq-xxx", "parentId-sq-0", or "questionId-blank-0" (new format)
+ */
+function isSyntheticSubQuestionId(questionId) {
+    return (questionId.startsWith('sq-') ||
+        questionId.includes('-sq-') ||
+        questionId.includes('-blank-') ||
+        questionId.includes('-item-'));
+}
+/**
+ * Check if key is a grid cell coordinate
+ * e.g., "1-2", "2-3" (row-column format)
+ */
+function isGridCellKey(key) {
+    return /^\d+-\d+$/.test(key);
+}
+/**
+ * Check if key is a label ID (from LABEL_THE_PICTURE)
+ * e.g., "label-xxx"
+ */
+function isLabelId(key) {
+    return key.startsWith('label-');
+}
+/**
+ * Check if key is a region ID (from READ_AND_COLOR_OBJECTS)
+ * e.g., "region-xxx"
+ */
+function isRegionId(key) {
+    return key.startsWith('region-');
+}
+/**
+ * Find parent question ID and question type for a sub-question
+ */
+function findParentQuestion(subQuestionId, parts) {
+    for (const part of parts) {
+        if (part.questionType === 'READ_PASSAGE_AND_ANSWER_QUESTIONS') {
+            if (part.questions.length > 0) {
+                return {
+                    parentId: part.questions[0].id,
+                    questionType: part.questionType,
+                };
+            }
+        }
+        if (part.questionType === 'CHOOSE_THE_CORRECT_ANSWER_GROUP' ||
+            part.questionType === 'CROSS_OUT_WORD_GROUP' ||
+            part.questionType === 'TRUE_FALSE_GROUP' ||
+            part.questionType === 'WORD_ORDER_AND_MATCH_GROUP' ||
+            part.questionType === 'SPONTANEOUS_QA_GROUP') {
+            const parent = part.questions.find((question) => subQuestionId.startsWith(`${question.id}-item-`));
+            if (parent) {
+                return {
+                    parentId: parent.id,
+                    questionType: part.questionType,
+                };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Find parent question for grid cells (FILL_MISSING_WORDS_IN_GRID)
+ */
+function findGridParentQuestion(parts) {
+    for (const part of parts) {
+        if (part.questionType === 'FILL_MISSING_WORDS_IN_GRID') {
+            if (part.questions.length > 0) {
+                return {
+                    parentId: part.questions[0].id,
+                    questionType: part.questionType,
+                };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Find parent question for labels (LABEL_THE_PICTURE)
+ */
+function findLabelParentQuestion(parts) {
+    for (const part of parts) {
+        if (part.questionType === 'LABEL_THE_PICTURE') {
+            if (part.questions.length > 0) {
+                return {
+                    parentId: part.questions[0].id,
+                    questionType: part.questionType,
+                };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Find parent question for regions (READ_AND_COLOR_OBJECTS / IMAGE_OBJECT_MATCHING)
+ * Now accepts regionId to find the correct parent question for that specific region
+ */
+function findColoringParentQuestion(regionId, parts) {
+    for (const part of parts) {
+        if (part.questionType === 'READ_AND_COLOR_OBJECTS' || part.questionType === 'IMAGE_OBJECT_MATCHING') {
+            if (part.questions.length > 0) {
+                const question = part.questions[0];
+                const content = question.content;
+                // Check if this part contains the region
+                const regions = content?.regions || content?.regionNodes || [];
+                const hasRegion = regions.some((r) => r.id === regionId);
+                if (hasRegion) {
+                    return {
+                        parentId: question.id,
+                        questionType: part.questionType,
+                    };
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Find parent question for sub-questions (LOOK_PICTURE_FILL_WORD_HINT)
+ * Supports both old format (content.subQuestions) and new format (questionId-blank-N)
+ */
+function findFillWordHintParentQuestion(subQuestionId, parts) {
+    for (const part of parts) {
+        if (part.questionType === 'LOOK_PICTURE_FILL_WORD_HINT') {
+            for (const question of part.questions) {
+                // NEW FORMAT: Check if subQuestionId matches pattern "questionId-blank-N"
+                if (subQuestionId.startsWith(`${question.id}-blank-`)) {
+                    return {
+                        parentId: question.id,
+                        questionType: part.questionType,
+                    };
+                }
+                // OLD FORMAT: Check subQuestions array in content
+                const content = question.content;
+                if (content?.subQuestions?.some((sq) => sq.id === subQuestionId)) {
+                    return {
+                        parentId: question.id,
+                        questionType: part.questionType,
+                    };
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Find question type by questionId
+ */
+function findQuestionType(questionId, parts) {
+    for (const part of parts) {
+        for (const q of part.questions) {
+            if (q.id === questionId) {
+                return part.questionType;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Wrap answer in proper format for backend grading
+ */
+function wrapAnswer(answer, questionType) {
+    // For single/multiple choice, wrap in { answer: value }
+    if (typeof answer === 'number') {
+        return { answer };
+    }
+    // For text answers (fill blank), wrap in { answer: text }
+    if (typeof answer === 'string') {
+        return { answer };
+    }
+    // For array answers (word fill with word bank), wrap in { answers: array }
+    // WORD_FILL_PARAGRAPH stores answers as array of strings
+    if (Array.isArray(answer)) {
+        if (questionType === 'WORD_FILL_PARAGRAPH') {
+            return { answers: answer };
+        }
+        // Fallback for other question types with array answers
+        return { answer };
+    }
+    // For object answers (sub-questions), wrap appropriately
+    if (typeof answer === 'object' && answer !== null) {
+        // Already an object, return as-is (e.g., sub-question answers)
+        return answer;
+    }
+    return { answer };
+}
+/**
+ * Transform frontend answers to API format
+ *
+ * @param answers - Record of questionId -> answer from store
+ * @param parts - Question parts for context
+ * @returns Array of SaveAnswerRequest ready for API
+ */
+export function transformAnswersForSubmission(answers, parts) {
+    const result = [];
+    const subQuestionAnswers = new Map();
+    const gridCellAnswers = new Map();
+    const labelAnswers = new Map();
+    const regionAnswers = new Map();
+    // Build a set of speaking question IDs whose audio is already saved via
+    // the dedicated uploadAudioAnswer endpoint (persisted to the audioKey column).
+    // The answer JSONB column is used by the grading service to store AI assessment
+    // results (aiAssessment, llmAssessment, classification). Re-saving the audioKey
+    // string here would overwrite that AI grading data.
+    const speakingQuestionIds = new Set();
+    for (const part of parts) {
+        for (const q of part.questions) {
+            if (q.question_skill_type === 'SPEAKING') {
+                speakingQuestionIds.add(q.id);
+            }
+        }
+    }
+    for (const [questionId, answer] of Object.entries(answers)) {
+        // Skip empty answers
+        if (answer === undefined || answer === null || answer === '') {
+            continue;
+        }
+        // Skip speaking questions — their audio is already saved via uploadAudioAnswer
+        // endpoint to the audioKey column. The answer column stores AI grading results
+        // (aiAssessment, llmAssessment, classification) written by the grading service.
+        // Sending the audioKey string here would overwrite those AI results.
+        if (speakingQuestionIds.has(questionId) && typeof answer === 'string') {
+            continue;
+        }
+        // Handle grid cell keys (from FILL_MISSING_WORDS_IN_GRID)
+        if (isGridCellKey(questionId)) {
+            const parent = findGridParentQuestion(parts);
+            if (parent) {
+                if (!gridCellAnswers.has(parent.parentId)) {
+                    gridCellAnswers.set(parent.parentId, {});
+                }
+                // Store grid cell answer - value should be a string
+                gridCellAnswers.get(parent.parentId)[questionId] = String(answer);
+            }
+            continue;
+        }
+        // Handle label IDs (from LABEL_THE_PICTURE)
+        if (isLabelId(questionId)) {
+            const parent = findLabelParentQuestion(parts);
+            if (parent) {
+                if (!labelAnswers.has(parent.parentId)) {
+                    labelAnswers.set(parent.parentId, {});
+                }
+                // Store label answer - value should be a string
+                labelAnswers.get(parent.parentId)[questionId] = String(answer);
+            }
+            continue;
+        }
+        // Handle region IDs (from READ_AND_COLOR_OBJECTS / IMAGE_OBJECT_MATCHING)
+        if (isRegionId(questionId)) {
+            const parent = findColoringParentQuestion(questionId, parts);
+            if (parent) {
+                if (!regionAnswers.has(parent.parentId)) {
+                    regionAnswers.set(parent.parentId, {});
+                }
+                // Store region answer - value should be hex color (e.g., "#FF0000")
+                regionAnswers.get(parent.parentId)[questionId] = String(answer);
+            }
+            continue;
+        }
+        // Handle synthetic sub-question IDs (from READ_PASSAGE_AND_ANSWER_QUESTIONS or LOOK_PICTURE_FILL_WORD_HINT)
+        if (isSyntheticSubQuestionId(questionId)) {
+            // Try READ_PASSAGE_AND_ANSWER_QUESTIONS first
+            let parent = findParentQuestion(questionId, parts);
+            // If not found, try LOOK_PICTURE_FILL_WORD_HINT
+            if (!parent) {
+                parent = findFillWordHintParentQuestion(questionId, parts);
+            }
+            if (parent) {
+                if (!subQuestionAnswers.has(parent.parentId)) {
+                    subQuestionAnswers.set(parent.parentId, {});
+                }
+                // Store sub-question answer - convert option ID to index if needed
+                const answerValue = isSyntheticOptionId(answer)
+                    ? extractOptionIndex(answer)
+                    : answer;
+                subQuestionAnswers.get(parent.parentId)[questionId] = answerValue;
+            }
+            continue;
+        }
+        // Find question type for proper formatting
+        const questionType = findQuestionType(questionId, parts);
+        // Handle regular questions - convert synthetic option IDs to proper format
+        let transformedAnswer;
+        if (isSyntheticOptionId(answer)) {
+            // Convert synthetic option ID to wrapped answer format
+            transformedAnswer = wrapAnswer(extractOptionIndex(answer), questionType);
+        }
+        else if (isSyntheticOptionIdArray(answer)) {
+            // Convert synthetic option IDs to wrapped numeric index array format
+            transformedAnswer = wrapAnswer(answer.map((optionId) => extractOptionIndex(optionId)), questionType);
+        }
+        else if (isAnswerObjectWithSyntheticOptionId(answer)) {
+            // English Certification (TOEIC) stores { optionId: "<qid>-opt-N" }; the
+            // synthetic optionId never matches the index-based correct answer, so
+            // convert it to { answer: N } like the other choice renderers.
+            transformedAnswer = wrapAnswer(extractOptionIndex(answer.optionId), questionType);
+        }
+        else {
+            // Wrap raw answer
+            transformedAnswer = wrapAnswer(answer, questionType);
+        }
+        result.push({
+            questionId,
+            answer: transformedAnswer,
+        });
+    }
+    // Add composite question answers (sub-questions grouped under parent)
+    for (const [parentId, subAnswers] of subQuestionAnswers) {
+        const hasItemIds = Object.keys(subAnswers).some((key) => key.includes('-item-'));
+        if (hasItemIds) {
+            const parentQuestion = parts
+                .flatMap((part) => part.questions)
+                .find((question) => question.id === parentId);
+            const itemCount = Array.isArray(parentQuestion?.content?.items)
+                ? parentQuestion.content.items.length
+                : 0;
+            const parentType = parts.find((part) => part.questions.some((question) => question.id === parentId))?.questionType || '';
+            // Group speaking answers are already persisted item-by-item through
+            // uploadGroupItemAudio. Sending synthetic child IDs via saveAnswers would
+            // overwrite the backend's audio/AI-assessment payload.
+            if (parentType === 'SPONTANEOUS_QA_GROUP') {
+                continue;
+            }
+            const answers = Array.from({ length: itemCount }, (_, index) => {
+                const raw = subAnswers[`${parentId}-item-${index}`];
+                if (parentType === 'CROSS_OUT_WORD_GROUP') {
+                    return normalizeCrossOutWordGroupAnswer(raw);
+                }
+                if (parentType === 'WORD_ORDER_AND_MATCH_GROUP') {
+                    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+                        const obj = raw;
+                        return {
+                            orderedPhrase: typeof obj.orderedPhrase === 'string' ? obj.orderedPhrase : '',
+                            matchLabel: typeof obj.matchLabel === 'string' ? obj.matchLabel : '',
+                        };
+                    }
+                    return { orderedPhrase: '', matchLabel: '' };
+                }
+                if (typeof raw === 'boolean')
+                    return raw;
+                return typeof raw === 'string' ? raw : '';
+            });
+            result.push({
+                questionId: parentId,
+                answer: { answer: answers },
+            });
+            continue;
+        }
+        // Check if this is LOOK_PICTURE_FILL_WORD_HINT with new format IDs
+        const hasBlankIds = Object.keys(subAnswers).some((key) => key.includes('-blank-'));
+        if (hasBlankIds) {
+            // NEW FORMAT: Convert to comma-separated string like correctAnswer
+            // Sort by blank index and join
+            const sortedEntries = Object.entries(subAnswers).sort(([a], [b]) => {
+                const aMatch = a.match(/-blank-(\d+)$/);
+                const bMatch = b.match(/-blank-(\d+)$/);
+                const aIdx = aMatch ? parseInt(aMatch[1], 10) : 0;
+                const bIdx = bMatch ? parseInt(bMatch[1], 10) : 0;
+                return aIdx - bIdx;
+            });
+            const commaSeparated = sortedEntries.map(([, v]) => v).join(', ');
+            result.push({
+                questionId: parentId,
+                answer: { answer: commaSeparated }, // Simple format: { answer: "a, e" }
+            });
+        }
+        else {
+            // OLD FORMAT or other question types: keep subAnswers format
+            result.push({
+                questionId: parentId,
+                answer: { subAnswers },
+            });
+        }
+    }
+    // Add grid cell answers (grouped under parent question)
+    for (const [parentId, cellAnswers] of gridCellAnswers) {
+        result.push({
+            questionId: parentId,
+            answer: { answers: cellAnswers },
+        });
+    }
+    // Add label answers (grouped under parent question)
+    for (const [parentId, labels] of labelAnswers) {
+        result.push({
+            questionId: parentId,
+            answer: { answers: labels },
+        });
+    }
+    // Add region answers (grouped under parent question)
+    for (const [parentId, regions] of regionAnswers) {
+        result.push({
+            questionId: parentId,
+            answer: { answers: regions },
+        });
+    }
+    return result;
+}
+/**
+ * Get all valid question IDs from parts
+ * Used to filter out invalid IDs before submission
+ */
+export function getValidQuestionIds(parts) {
+    const ids = new Set();
+    for (const part of parts) {
+        for (const question of part.questions) {
+            ids.add(question.id);
+        }
+    }
+    return ids;
+}

package/dist/components/exams/take/utils/cambridge-yle-inline-speaking.d.ts

@@ -0,0 +1,21 @@
+export declare const CAMBRIDGE_YLE_INLINE_SPEAKING_TYPES: readonly ["SPEAKING_DESCRIBE_IMAGE", "SPONTANEOUS_QA", "SPONTANEOUS_QA_GROUP", "SPEAKING_CUE_CARD", "READ_DISPLAYED_CONTENT"];
+export type CambridgeYleInlineSpeakingType = (typeof CAMBRIDGE_YLE_INLINE_SPEAKING_TYPES)[number];
+export declare function isCambridgeYleInlineSpeakingType(questionType: string | undefined): questionType is CambridgeYleInlineSpeakingType;
+export declare function getSpontaneousQaGroupChildCount(content: unknown): number;
+export declare function toSpontaneousQaGroupItemId(parentId: string, itemIndex: number): string;
+export declare function listSpontaneousQaGroupChildIds(parentId: string, content: unknown): string[];
+export declare function getCambridgeYlePartQuestionCount(part: {
+    questionType?: string;
+    questions: Array<{
+        content?: unknown;
+    }>;
+}): number;
+export declare function getPartInitialQuestionIndex(part: {
+    questionType?: string;
+    questions: Array<{
+        content?: unknown;
+    }>;
+} | undefined, direction: 'forward' | 'backward'): number;
+export declare function findSidebarQuestionForPart<T extends {
+    partIndex: number;
+}>(sidebarQuestions: T[], partIndex: number, direction?: 'forward' | 'backward'): T | undefined;

package/dist/components/exams/take/utils/cambridge-yle-inline-speaking.js

@@ -0,0 +1,44 @@
+import { flattenSpontaneousQaGroupContent } from '../../../questions/types/spontaneous-qa-group/flatten';
+export const CAMBRIDGE_YLE_INLINE_SPEAKING_TYPES = [
+    'SPEAKING_DESCRIBE_IMAGE',
+    'SPONTANEOUS_QA',
+    'SPONTANEOUS_QA_GROUP',
+    'SPEAKING_CUE_CARD',
+    'READ_DISPLAYED_CONTENT',
+];
+export function isCambridgeYleInlineSpeakingType(questionType) {
+    return (!!questionType &&
+        CAMBRIDGE_YLE_INLINE_SPEAKING_TYPES.includes(questionType));
+}
+export function getSpontaneousQaGroupChildCount(content) {
+    return flattenSpontaneousQaGroupContent(content).length;
+}
+export function toSpontaneousQaGroupItemId(parentId, itemIndex) {
+    return `${parentId}-item-${itemIndex}`;
+}
+export function listSpontaneousQaGroupChildIds(parentId, content) {
+    const count = getSpontaneousQaGroupChildCount(content);
+    return Array.from({ length: count }, (_, index) => toSpontaneousQaGroupItemId(parentId, index));
+}
+export function getCambridgeYlePartQuestionCount(part) {
+    if (part.questionType === 'SPONTANEOUS_QA_GROUP') {
+        return getSpontaneousQaGroupChildCount(part.questions[0]?.content);
+    }
+    return part.questions.length;
+}
+export function getPartInitialQuestionIndex(part, direction) {
+    if (!part || direction !== 'backward')
+        return 0;
+    return Math.max(getCambridgeYlePartQuestionCount(part) - 1, 0);
+}
+export function findSidebarQuestionForPart(sidebarQuestions, partIndex, direction = 'forward') {
+    if (direction === 'backward') {
+        for (let index = sidebarQuestions.length - 1; index >= 0; index -= 1) {
+            if (sidebarQuestions[index].partIndex === partIndex) {
+                return sidebarQuestions[index];
+            }
+        }
+        return undefined;
+    }
+    return sidebarQuestions.find((question) => question.partIndex === partIndex);
+}

package/dist/components/exams/take/utils/coloring-assignments.js

@@ -1 +1,40 @@
-function t(t){return"object"==typeof t&&null!==t}export function normalizeColoringAssignments(n,r){if(!t(n))return{};const o={};return Object.entries(n).forEach(([n,i])=>{const e=function(n){if("string"==typeof n)return n;if(!t(n))return null;const r=["hintItemId","id","value","color"];for(const t of r){const r=n[t];if("string"==typeof r&&r.trim())return r}return null}(i);if(e){if(e.startsWith("#")){const t=r.find(t=>t.color===e);return void(t&&(o[n]=t.id))}o[n]=e}}),o}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function extractAssignmentValue(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (!isRecord(value)) {
+        return null;
+    }
+    const candidateKeys = ['hintItemId', 'id', 'value', 'color'];
+    for (const key of candidateKeys) {
+        const candidate = value[key];
+        if (typeof candidate === 'string' && candidate.trim()) {
+            return candidate;
+        }
+    }
+    return null;
+}
+export function normalizeColoringAssignments(rawAssignments, hintItems) {
+    if (!isRecord(rawAssignments)) {
+        return {};
+    }
+    const assignments = {};
+    Object.entries(rawAssignments).forEach(([regionId, rawValue]) => {
+        const normalizedValue = extractAssignmentValue(rawValue);
+        if (!normalizedValue) {
+            return;
+        }
+        if (normalizedValue.startsWith('#')) {
+            const hint = hintItems.find((item) => item.color === normalizedValue);
+            if (hint) {
+                assignments[regionId] = hint.id;
+            }
+            return;
+        }
+        assignments[regionId] = normalizedValue;
+    });
+    return assignments;
+}

package/dist/components/exams/take/utils/cross-out-word-group.transformer.d.ts

@@ -0,0 +1,21 @@
+import type { ApiQuestion } from './question-transformers';
+export type CrossOutWordItemMode = 'CROSS_OUT' | 'CROSS_OUT_AND_REPLACE';
+export interface CrossOutWordGroupItemAnswer {
+    type: CrossOutWordItemMode;
+    wordIndex?: number | null;
+    crossOut: string;
+    replaceWith?: string;
+}
+export interface CrossOutWordGroupQuestion {
+    id: string;
+    questionNumber: number;
+    question: string;
+    type: CrossOutWordItemMode;
+    isExample: boolean;
+    exampleCorrectAnswer?: CrossOutWordGroupItemAnswer;
+}
+export declare function transformCrossOutWordGroup(questions: ApiQuestion[]): {
+    questions: CrossOutWordGroupQuestion[];
+    instruction: string;
+};
+export declare function normalizeCrossOutWordGroupAnswer(raw: unknown): CrossOutWordGroupItemAnswer;

package/dist/components/exams/take/utils/cross-out-word-group.transformer.js

@@ -0,0 +1,83 @@
+const DEFAULT_INSTRUCTION = 'Cross out the extra or incorrect word. If the word is incorrect, write the correct word. If the line is correct, leave it blank.';
+function normalizeMode(type) {
+    return type === 'CROSS_OUT_AND_REPLACE' ? 'CROSS_OUT_AND_REPLACE' : 'CROSS_OUT';
+}
+function normalizeAnswer(rawAnswer, type) {
+    const rawIndex = rawAnswer?.wordIndex;
+    const wordIndex = typeof rawIndex === 'number' && Number.isInteger(rawIndex) && rawIndex >= 0
+        ? rawIndex
+        : rawIndex === null
+            ? null
+            : undefined;
+    if (type === 'CROSS_OUT_AND_REPLACE') {
+        return {
+            type: 'CROSS_OUT_AND_REPLACE',
+            ...(wordIndex !== undefined ? { wordIndex } : {}),
+            crossOut: rawAnswer?.crossOut || '',
+            replaceWith: rawAnswer?.replaceWith || '',
+        };
+    }
+    return {
+        type: 'CROSS_OUT',
+        ...(wordIndex !== undefined ? { wordIndex } : {}),
+        crossOut: rawAnswer?.crossOut || '',
+    };
+}
+export function transformCrossOutWordGroup(questions) {
+    const parent = questions[0];
+    if (!parent) {
+        return { questions: [], instruction: DEFAULT_INSTRUCTION };
+    }
+    const content = parent.content;
+    const items = Array.isArray(content?.items) ? content.items : [];
+    const parentCorrect = Array.isArray(parent.correct_answer?.answer)
+        ? parent.correct_answer.answer
+        : [];
+    const transformed = items.map((item, index) => {
+        const type = normalizeMode(item.content?.type ||
+            item.correctAnswer?.answer?.type ||
+            parentCorrect[index]?.type);
+        const rawAnswer = item.correctAnswer?.answer ||
+            parentCorrect[index];
+        const isExample = item.isExample === true;
+        return {
+            id: `${parent.id}-item-${index}`,
+            questionNumber: item.questionNumber || index + 1,
+            question: item.content?.question || '',
+            type,
+            isExample,
+            exampleCorrectAnswer: isExample && rawAnswer
+                ? normalizeAnswer(rawAnswer, type)
+                : undefined,
+        };
+    });
+    return {
+        questions: transformed,
+        instruction: content?.meta?.instruction || DEFAULT_INSTRUCTION,
+    };
+}
+export function normalizeCrossOutWordGroupAnswer(raw) {
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        const obj = raw;
+        const type = normalizeMode(obj.type);
+        const rawIndex = obj.wordIndex;
+        const wordIndex = typeof rawIndex === 'number' && Number.isInteger(rawIndex) && rawIndex >= 0
+            ? rawIndex
+            : rawIndex === null
+                ? null
+                : undefined;
+        return type === 'CROSS_OUT_AND_REPLACE'
+            ? {
+                type,
+                ...(wordIndex !== undefined ? { wordIndex } : {}),
+                crossOut: typeof obj.crossOut === 'string' ? obj.crossOut : '',
+                replaceWith: typeof obj.replaceWith === 'string' ? obj.replaceWith : '',
+            }
+            : {
+                type: 'CROSS_OUT',
+                ...(wordIndex !== undefined ? { wordIndex } : {}),
+                crossOut: typeof obj.crossOut === 'string' ? obj.crossOut : '',
+            };
+    }
+    return { type: 'CROSS_OUT', crossOut: '' };
+}