@tinyweb_dev/oe-exam-sdk 0.2.6 → 0.2.8

package/dist/components/questions/types/fill-in-blank/register.js

@@ -1,4 +1,5 @@
 import { FillInBlankCreator } from './FillInBlankCreator';
+import { normalizeFillInBlankAnswers } from './answer-utils';
 export const fillInBlankRegistration = {
     component: FillInBlankCreator,
     transformInitialData: (initialData) => {
@@ -18,14 +19,16 @@ export const fillInBlankRegistration = {
         const groupTitle = groupPayload?.title || answer?.title || '';
         const groupContent = groupPayload?.content || groupPayload?.passage || answer?.groupContent || '';
         const groupNumber = questionGroup?.groupNumber || answer?.groupNumber || 1;
+        const audioUrl = answer?.audioUrl || content?.audioUrl || '';
         // NEW FORMAT: question with {0}, {1}, {2}... placeholders and answers array
         if (answer?.question && Array.isArray(answer?.answers)) {
             creatorData = {
                 question: answer.question,
-                answers: answer.answers,
+                answers: normalizeFillInBlankAnswers(answer.answers),
                 caseSensitive: answer?.caseSensitive ?? false,
                 imageUrl: questionImageUrl,
                 groupImageUrl,
+                audioUrl,
                 showHints: answer?.showHints || false,
                 hints: answer?.hints || [],
                 explanation,
@@ -40,10 +43,11 @@ export const fillInBlankRegistration = {
         else if (content?.question && Array.isArray(answer?.answers)) {
             creatorData = {
                 question: content.question,
-                answers: answer.answers,
+                answers: normalizeFillInBlankAnswers(answer.answers),
                 caseSensitive: answer?.caseSensitive ?? false,
                 imageUrl: questionImageUrl,
                 groupImageUrl,
+                audioUrl,
                 showHints: content?.showHints || false,
                 hints: content?.hints || [],
                 explanation,
@@ -60,7 +64,7 @@ export const fillInBlankRegistration = {
             const firstBlank = answer.blanks[0];
             creatorData = {
                 question: firstBlank?.text || '',
-                answers: answer.blanks.map((b) => b.correctAnswer || ''),
+                answers: normalizeFillInBlankAnswers(answer.blanks.map((b) => b.correctAnswers ?? b.correctAnswer ?? '')),
                 caseSensitive: answer?.caseSensitive ?? false,
                 showHints: answer?.showHints || false,
                 hints: answer?.hints || [],
@@ -69,6 +73,7 @@ export const fillInBlankRegistration = {
                 blanks: answer.blanks,
                 imageUrl: questionImageUrl,
                 groupImageUrl,
+                audioUrl,
                 title: groupTitle,
                 groupContent,
                 groupNumber,
@@ -79,7 +84,7 @@ export const fillInBlankRegistration = {
             // LEGACY Format 1: Single blank
             creatorData = {
                 question: content.text || '',
-                answers: [answer?.correctAnswer || ''],
+                answers: normalizeFillInBlankAnswers([answer?.correctAnswer || '']),
                 caseSensitive: answer?.caseSensitive ?? false,
                 showHints: content?.showHints || false,
                 hints: content?.hints || [],
@@ -87,6 +92,7 @@ export const fillInBlankRegistration = {
                 isExample: initialData?.isExample || answer?.isExample || false,
                 imageUrl: questionImageUrl,
                 groupImageUrl,
+                audioUrl,
                 title: groupTitle,
                 groupContent,
                 groupNumber,
@@ -98,12 +104,17 @@ export const fillInBlankRegistration = {
             const answersMap = answer?.answers || {};
             const mergedBlanks = content.blanks.map((blank) => ({
                 ...blank,
-                correctAnswer: answersMap[blank.id] || blank.correctAnswer || '',
+                correctAnswer: Array.isArray(answersMap[blank.id])
+                    ? (answersMap[blank.id][0] || blank.correctAnswer || '')
+                    : (answersMap[blank.id] || blank.correctAnswer || ''),
+                correctAnswers: Array.isArray(answersMap[blank.id])
+                    ? answersMap[blank.id]
+                    : undefined,
             }));
             const firstBlank = mergedBlanks[0];
             creatorData = {
                 question: firstBlank?.text || '',
-                answers: mergedBlanks.map((b) => b.correctAnswer || ''),
+                answers: normalizeFillInBlankAnswers(mergedBlanks.map((b) => b.correctAnswers ?? b.correctAnswer ?? '')),
                 caseSensitive: answer?.caseSensitive ?? false,
                 showHints: content?.showHints || false,
                 hints: content?.hints || [],
@@ -112,6 +123,7 @@ export const fillInBlankRegistration = {
                 blanks: mergedBlanks,
                 imageUrl: questionImageUrl,
                 groupImageUrl,
+                audioUrl,
                 title: groupTitle,
                 groupContent,
                 groupNumber,
@@ -126,6 +138,7 @@ export const fillInBlankRegistration = {
         groups: ctx.groups,
         questionIndexInPart: ctx.questionIndexInPart,
         partId: ctx.partId,
+        questionConfig: ctx.questionConfig,
     }),
     wrapOnSave: (data, ctx) => ({
         type: ctx.questionType,

package/dist/components/questions/types/fill-in-blank/transform.js

@@ -1,21 +1,4 @@
-function extractPlaceholderIndices(question) {
-    if (!question)
-        return [];
-    const regex = /\{(\d+)\}/g;
-    const indices = [];
-    let match;
-    while ((match = regex.exec(question)) !== null) {
-        const index = parseInt(match[1], 10);
-        if (!indices.includes(index)) {
-            indices.push(index);
-        }
-    }
-    return indices.sort((a, b) => a - b);
-}
-function getMaxPlaceholderIndex(question) {
-    const indices = extractPlaceholderIndices(question);
-    return indices.length > 0 ? Math.max(...indices) : -1;
-}
+import { compactFillInBlankAnswers, normalizeFillInBlankAnswers, getMaxPlaceholderIndex } from './answer-utils';
 export const transformFillInBlank = (question) => {
     const answerData = question.answer;
     // Helper: build basicGroupData if any group field is present.
@@ -32,12 +15,8 @@ export const transformFillInBlank = (question) => {
         : undefined;
     const groupNumber = answerData?.groupNumber || 1;
     // NEW FORMAT: question with {0}, {1}, {2}... placeholders and answers array
+    // answers: string[][] (canonical) or legacy string[]
     if (answerData?.question && Array.isArray(answerData?.answers)) {
-        const maxIndex = getMaxPlaceholderIndex(answerData.question || '');
-        const requiredLength = maxIndex >= 0 ? maxIndex + 1 : 1;
-        const validAnswers = answerData.answers.length > requiredLength
-            ? answerData.answers.slice(0, requiredLength)
-            : answerData.answers;
         const apiContent = {
             question: answerData.question,
             showHints: answerData.showHints || false,
@@ -47,10 +26,17 @@ export const transformFillInBlank = (question) => {
         if (answerData.imageUrl) {
             apiContent.imageUrl = answerData.imageUrl;
         }
+        // Per-question audio (when questionConfig includes "audio")
+        if (answerData.audioUrl) {
+            apiContent.audioUrl = answerData.audioUrl;
+        }
+        const maxIndex = getMaxPlaceholderIndex(answerData.question || '');
+        const requiredLength = maxIndex >= 0 ? maxIndex + 1 : undefined;
+        const normalizedAnswers = compactFillInBlankAnswers(normalizeFillInBlankAnswers(answerData.answers, requiredLength), requiredLength);
         return {
             apiContent,
             apiCorrectAnswer: {
-                answers: validAnswers,
+                answers: normalizedAnswers,
                 caseSensitive: answerData.caseSensitive || false,
             },
             isExample: answerData.isExample || false,
@@ -66,9 +52,17 @@ export const transformFillInBlank = (question) => {
         id: blank.id,
         text: blank.text,
     }));
+    // Prefer correctAnswers[]; fall back to single correctAnswer string
     const answers = (answerData.blanks || []).reduce((acc, blank) => {
-        if (blank.id && blank.correctAnswer) {
-            acc[blank.id] = blank.correctAnswer;
+        if (!blank.id)
+            return acc;
+        const alts = blank.correctAnswers ?? blank.correctAnswer;
+        if (alts == null)
+            return acc;
+        const normalized = normalizeFillInBlankAnswers(Array.isArray(alts) ? [alts] : [alts])[0];
+        const cleaned = normalized.map((a) => a.trim()).filter(Boolean);
+        if (cleaned.length > 0) {
+            acc[blank.id] = cleaned;
         }
         return acc;
     }, {});
@@ -76,6 +70,9 @@ export const transformFillInBlank = (question) => {
     if (answerData.imageUrl) {
         legacyContent.imageUrl = answerData.imageUrl;
     }
+    if (answerData.audioUrl) {
+        legacyContent.audioUrl = answerData.audioUrl;
+    }
     return {
         apiContent: legacyContent,
         apiCorrectAnswer: {

package/dist/components/results/renderers/ReviewChooseBestAnswerRenderer.js

@@ -43,7 +43,7 @@ function ReviewQuestionItem({ question, selectedOptionIds, isCorrect, correctOpt
         }
         return _jsx("div", { className: `flex h-5 w-5 items-center justify-center border-2 border-gray-300 bg-white ${shapeClass}` });
     };
-    return (_jsxs("div", { className: "mb-4", children: [_jsxs("p", { className: "mb-2 text-lg font-bold text-gray-900", children: [question.questionNumber, ". ", question.questionText] }), isMultipleAnswers && (_jsx("p", { className: "mb-3 pl-2 text-sm font-medium text-blue-600", children: "Ch\u1ECDn nhi\u1EC1u \u0111\u00E1p \u00E1n" })), _jsx(ChooseBestAnswerImages, { imageUrl: question.imageUrl, className: "mb-3" }), isImageOptions ? (_jsx("div", { className: "grid gap-3 px-2", style: { gridTemplateColumns: `repeat(${question.options.length}, minmax(0, 1fr))` }, children: question.options.map((option) => (_jsxs("div", { className: `relative flex flex-col items-center gap-1 rounded-lg border-2 p-2 cursor-default ${getOptionStyle(option.id)}`, children: [_jsx("span", { className: "text-xs font-medium text-gray-600", children: option.label }), _jsx(ResolvedImage, { src: getChooseBestAnswerOptionImageSrc(option), alt: `Option ${option.label}`, className: "h-28 w-28 rounded object-contain" }), renderIndicator(option.id)] }, option.id))) })) : (
+    return (_jsxs("div", { className: "mb-4", children: [_jsxs("p", { className: "mb-2 text-lg font-bold text-gray-900", children: [question.questionNumber, ". ", question.questionText] }), isMultipleAnswers && (_jsx("p", { className: "mb-3 pl-2 text-sm font-medium text-blue-600", children: "Ch\u1ECDn nhi\u1EC1u \u0111\u00E1p \u00E1n" })), question.audioUrl && (_jsx("div", { className: "mb-3", children: _jsx(CambridgeYleAudioPlayer, { audioSrc: question.audioUrl, compact: true }) })), _jsx(ChooseBestAnswerImages, { imageUrl: question.imageUrl, className: "mb-3" }), isImageOptions ? (_jsx("div", { className: "grid gap-3 px-2", style: { gridTemplateColumns: `repeat(${question.options.length}, minmax(0, 1fr))` }, children: question.options.map((option) => (_jsxs("div", { className: `relative flex flex-col items-center gap-1 rounded-lg border-2 p-2 cursor-default ${getOptionStyle(option.id)}`, children: [_jsx("span", { className: "text-xs font-medium text-gray-600", children: option.label }), _jsx(ResolvedImage, { src: getChooseBestAnswerOptionImageSrc(option), alt: `Option ${option.label}`, className: "h-28 w-28 rounded object-contain" }), renderIndicator(option.id)] }, option.id))) })) : (
             /* Options — text variant */
             _jsx("div", { className: "flex flex-col gap-2 pl-2", children: question.options.map((option) => (_jsxs("div", { className: `flex items-center gap-3 rounded-lg border-2 px-3 py-2 cursor-default ${getOptionStyle(option.id)}`, children: [_jsxs("span", { className: "text-sm font-medium text-gray-600", children: [option.label, "."] }), _jsx("span", { className: "flex-1 text-sm text-gray-700", children: option.text }), renderIndicator(option.id)] }, option.id))) }))] }));
 }

package/dist/components/results/renderers/ReviewListenAndWriteRenderer.d.ts

@@ -10,9 +10,8 @@ interface ReviewListenAndWriteRendererProps {
     exampleText?: string;
     exampleHighlight?: string;
     questions: FillBlankQuestion[];
-    answers: Record<string, string>;
+    answers: Record<string, unknown>;
     isCorrectMap: Record<string, boolean | null>;
-    correctAnswerTextMap: Record<string, string>;
 }
-export declare function ReviewListenAndWriteRenderer({ partNumber, questionCount, instruction, partName, audioUrl, title, exampleText, questions, answers, isCorrectMap, correctAnswerTextMap, }: ReviewListenAndWriteRendererProps): import("react").JSX.Element;
+export declare function ReviewListenAndWriteRenderer({ partNumber, questionCount, instruction, partName, audioUrl, title, exampleText, questions, answers, isCorrectMap, }: ReviewListenAndWriteRendererProps): import("react").JSX.Element;
 export {};

package/dist/components/results/renderers/ReviewListenAndWriteRenderer.js

@@ -5,7 +5,8 @@ import { ResolvedImage } from '../../../components/common/ResolvedImage';
 import CambridgeYlePartBanner from '../../../components/themes/cambridge-yle/CambridgeYlePartBanner';
 import CambridgeYleInstructionBanner from '../../../components/themes/cambridge-yle/CambridgeYleInstructionBanner';
 import CambridgeYleAudioPlayer from '../../../components/themes/cambridge-yle/CambridgeYleAudioPlayer';
-export function ReviewListenAndWriteRenderer({ partNumber, questionCount, instruction, partName, audioUrl, title, exampleText, questions, answers, isCorrectMap, correctAnswerTextMap, }) {
+import { countBlanks, formatAcceptedAnswers, hasAnyBlankValue, isBlankCorrect, toBlankValues, } from '../../../shared/lib/utils/fill-in-blank';
+export function ReviewListenAndWriteRenderer({ partNumber, questionCount, instruction, partName, audioUrl, title, exampleText, questions, answers, isCorrectMap, }) {
     /**
      * Get answer status from API's isCorrect field
      * Returns: 'correct' | 'incorrect' | 'unanswered'
@@ -14,7 +15,7 @@ export function ReviewListenAndWriteRenderer({ partNumber, questionCount, instru
         const isCorrect = isCorrectMap[questionId];
         const userAnswer = answers[questionId];
         // No answer from student (null or undefined or empty string)
-        if (userAnswer === null || userAnswer === undefined || userAnswer === '') {
+        if (!hasAnyBlankValue(userAnswer)) {
             return 'unanswered';
         }
         // Use API's isCorrect value
@@ -25,8 +26,7 @@ export function ReviewListenAndWriteRenderer({ partNumber, questionCount, instru
         // isCorrect is null but student answered - treat as unanswered/pending
         return 'unanswered';
     };
-    const getUnderlineColor = (questionId) => {
-        const status = getAnswerStatus(questionId);
+    const getUnderlineColor = (status) => {
         switch (status) {
             case 'correct':
                 return '#22c55e'; // green-500
@@ -38,11 +38,20 @@ export function ReviewListenAndWriteRenderer({ partNumber, questionCount, instru
                 return '#9ca3af'; // gray-400
         }
     };
+    const renderBlankAnswer = (status, userValue, correctValue) => (_jsxs("span", { className: "mx-1 inline-block min-w-[120px] align-baseline", style: { borderBottom: `2px solid ${getUnderlineColor(status)}` }, children: [status === 'correct' && (_jsx("span", { className: "block w-full text-center", children: userValue })), status === 'unanswered' && (_jsx("span", { className: "block w-full text-center text-blue-600", children: correctValue })), status === 'incorrect' && (_jsxs("span", { className: "flex items-center justify-center gap-2", children: [_jsx("span", { className: "text-red-500 line-through", children: userValue }), _jsx("span", { className: "text-gray-400", children: "\u00E2\u2020\u2019" }), _jsx("span", { className: "text-blue-600", children: correctValue })] }))] }));
+    const getPerBlankStatus = (overall, userValue, accepted) => {
+        if (overall === 'unanswered' || !userValue.trim())
+            return 'unanswered';
+        return isBlankCorrect(userValue, accepted) ? 'correct' : 'incorrect';
+    };
     return (_jsxs("div", { className: "flex flex-col gap-6 h-full", children: [_jsxs("div", { className: "flex flex-col gap-4 pb-0 pt-4", children: [_jsx(CambridgeYlePartBanner, { partNumber: partNumber, questionCount: questionCount, partName: partName, isReviewMode: true }), _jsx(CambridgeYleInstructionBanner, { instruction: instruction, hasExample: !!exampleText, isReviewMode: true }), audioUrl && _jsx(CambridgeYleAudioPlayer, { audioSrc: audioUrl, compact: true })] }), _jsxs("div", { className: "flex flex-col gap-6 pb-6 pl-2 pt-2", children: [_jsx("h2", { className: "text-center text-3xl font-bold uppercase text-coral-500", children: title }), _jsx("div", { className: "flex flex-col gap-4", children: questions.map((question) => {
                             const status = getAnswerStatus(question.id);
-                            const userAnswer = answers[question.id] || '';
-                            return (_jsxs("div", { className: "flex flex-col gap-2", children: [question.imageUrl && (_jsx("div", { className: "flex items-center justify-center", children: _jsx(ResolvedImage, { src: question.imageUrl, alt: `Question ${question.questionNumber} illustration`, className: "max-h-[150px] rounded-lg object-contain shadow-md" }) })), _jsxs("div", { className: "flex items-start gap-2", children: [_jsx("span", { className: "flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-full bg-blue-500 text-sm font-bold text-white", children: question.questionNumber }), _jsx("div", { className: "flex-1 text-base leading-relaxed text-gray-800", children: _jsxs("div", { className: "flex items-center gap-2", children: [question.textBefore && (_jsx("span", { children: question.textBefore })), _jsxs("span", { className: "inline-block min-w-[120px]", style: {
-                                                                borderBottom: `2px solid ${getUnderlineColor(question.id)}`,
-                                                            }, children: [status === 'correct' && (_jsx("span", { className: "block w-full text-center", children: userAnswer })), status === 'unanswered' && (_jsx("span", { className: "block w-full text-center text-blue-600", children: correctAnswerTextMap[question.id] })), status === 'incorrect' && (_jsxs("span", { className: "flex items-center justify-center gap-2", children: [_jsx("span", { className: "text-red-500 line-through", children: userAnswer }), _jsx("span", { className: "text-gray-400", children: "\u2192" }), _jsx("span", { className: "text-blue-600", children: correctAnswerTextMap[question.id] })] }))] }), question.textAfter && (_jsx("span", { children: question.textAfter })), status === 'correct' && (_jsx("div", { className: "flex h-6 w-6 items-center justify-center rounded-full bg-green-500", children: _jsx(Check, { className: "h-4 w-4 text-white", strokeWidth: 3 }) })), status === 'incorrect' && (_jsx("div", { className: "flex h-6 w-6 items-center justify-center rounded-full bg-red-500", children: _jsx(X, { className: "h-4 w-4 text-white", strokeWidth: 3 }) })), status === 'unanswered' && (_jsx("div", { className: "flex h-6 w-6 items-center justify-center rounded-full bg-blue-500", children: _jsx(Check, { className: "h-4 w-4 text-white", strokeWidth: 3 }) }))] }) })] })] }, question.id));
+                            const userValues = toBlankValues(answers[question.id], countBlanks(question.segments));
+                            const renderBlank = (blankIndex) => {
+                                const userValue = userValues[blankIndex] || '';
+                                const accepted = question.acceptedAnswers[blankIndex];
+                                return renderBlankAnswer(getPerBlankStatus(status, userValue, accepted), userValue, formatAcceptedAnswers(accepted));
+                            };
+                            return (_jsxs("div", { className: "flex flex-col gap-2", children: [question.audioUrl && (_jsx("div", { className: "w-full max-w-md", children: _jsx(CambridgeYleAudioPlayer, { audioSrc: question.audioUrl, compact: true }) })), question.imageUrl && (_jsx("div", { className: "flex items-center justify-center", children: _jsx(ResolvedImage, { src: question.imageUrl, alt: `Question ${question.questionNumber} illustration`, className: "max-h-[150px] rounded-lg object-contain shadow-md" }) })), _jsxs("div", { className: "flex items-start gap-2", children: [_jsx("span", { className: "flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-full bg-blue-500 text-sm font-bold text-white", children: question.questionNumber }), _jsx("div", { className: "flex-1 text-base leading-relaxed text-gray-800", children: _jsxs("div", { className: "leading-loose", children: [question.segments.map((segment, segmentIndex) => segment.type === 'text' ? (_jsx("span", { children: segment.value }, `text-${segmentIndex}`)) : (_jsx("span", { children: renderBlank(segment.index) }, `blank-${segment.index}-${segmentIndex}`))), status === 'correct' && (_jsx("div", { className: "ml-2 inline-flex h-6 w-6 items-center justify-center rounded-full bg-green-500 align-middle", children: _jsx(Check, { className: "h-4 w-4 text-white", strokeWidth: 3 }) })), status === 'incorrect' && (_jsx("div", { className: "ml-2 inline-flex h-6 w-6 items-center justify-center rounded-full bg-red-500 align-middle", children: _jsx(X, { className: "h-4 w-4 text-white", strokeWidth: 3 }) })), status === 'unanswered' && (_jsx("div", { className: "ml-2 inline-flex h-6 w-6 items-center justify-center rounded-full bg-blue-500 align-middle", children: _jsx(Check, { className: "h-4 w-4 text-white", strokeWidth: 3 }) }))] }) })] })] }, question.id));
                         }) })] })] }));
 }

package/dist/components/results/renderers/review-question-body-dedicated.js

@@ -28,11 +28,11 @@ export function renderDedicatedReviewBody(ctx) {
     switch (questionType) {
         case 'FILL_IN_BLANK': {
             const data = transformFillInBlank(apiQuestions);
-            return (_jsx(ReviewListenAndWriteRenderer, { partNumber: partNo, questionCount: questionCount, partName: part.name, instruction: part.instructions || data.instruction, title: data.title, imageUrl: data.imageUrl, audioUrl: data.audioUrl, exampleText: data.exampleText, exampleHighlight: data.exampleHighlight, questions: data.questions, answers: answers, isCorrectMap: isCorrectMap, correctAnswerTextMap: correctAnswerTextMap }));
+            return (_jsx(ReviewListenAndWriteRenderer, { partNumber: partNo, questionCount: questionCount, partName: part.name, instruction: part.instructions || data.instruction, title: data.title, imageUrl: data.imageUrl, audioUrl: data.audioUrl, exampleText: data.exampleText, exampleHighlight: data.exampleHighlight, questions: data.questions, answers: answers, isCorrectMap: isCorrectMap }));
         }
         case 'WRITE_CORRECT_VERB_FORM': {
             const data = transformWriteCorrectVerbForm(apiQuestions);
-            return (_jsx(ReviewListenAndWriteRenderer, { partNumber: partNo, questionCount: questionCount, partName: part.name, instruction: part.instructions || data.instruction, title: data.title, questions: data.questions, answers: answers, isCorrectMap: isCorrectMap, correctAnswerTextMap: correctAnswerTextMap }));
+            return (_jsx(ReviewListenAndWriteRenderer, { partNumber: partNo, questionCount: questionCount, partName: part.name, instruction: part.instructions || data.instruction, title: data.title, questions: data.questions, answers: answers, isCorrectMap: isCorrectMap }));
         }
         case 'CHOOSE_THE_CORRECT_ANSWER': {
             const data = transformChooseCorrectAnswer(apiQuestions);
@@ -40,7 +40,7 @@ export function renderDedicatedReviewBody(ctx) {
         }
         case 'CHOOSE_THE_CORRECT_ANSWER_GROUP': {
             const data = transformChooseTheCorrectAnswerGroup(apiQuestions);
-            return (_jsx(ReviewChooseBestAnswerRenderer, { partNumber: partNo, questionCount: questionCount, partName: part.name, instruction: part.instructions || data.instruction, questions: data.questions, answers: answers, isCorrectMap: isCorrectMap, correctOptionIdMap: correctOptionIdMap, example: data.example }));
+            return (_jsx(ReviewChooseBestAnswerRenderer, { partNumber: partNo, questionCount: questionCount, partName: part.name, instruction: part.instructions || data.instruction, audioUrl: data.audioUrl, questions: data.questions, answers: answers, isCorrectMap: isCorrectMap, correctOptionIdMap: correctOptionIdMap, example: data.example }));
         }
         case 'CHOOSE_CORRECT_ADJECTIVE': {
             const data = transformChooseCorrectAdjective(apiQuestions);

package/dist/shared/lib/utils/fill-in-blank.d.ts

@@ -0,0 +1,46 @@
+/**
+ * FILL_IN_BLANK — single source of truth for the whole flow.
+ *
+ * Wire format (never change one side without the other):
+ *   content.question       "A dog {0} swim, but it {1} fly."
+ *   correct_answer.answers string[][] — answers[i] = accepted equivalents for blank {i}
+ *   student answer         { answers: string[] } — one entry per blank, index-aligned
+ *
+ * Matching rule (mirrors the API `normalizeText`): trim, lowercase, collapse inner
+ * whitespace, keep diacritics. A blank is correct when the input equals ANY equivalent.
+ */
+export type FillBlankSegment = {
+    type: 'text';
+    value: string;
+} | {
+    type: 'blank';
+    index: number;
+};
+/** Split a stem into the text / blank segments used by every renderer. */
+export declare function parseFillBlankSegments(text: string): FillBlankSegment[];
+/**
+ * Renderer-facing parse: like `parseFillBlankSegments`, but guarantees at least
+ * one blank so a stem authored without `{0}` still gets an input box.
+ */
+export declare function parseFillBlankStem(text: string): FillBlankSegment[];
+/** Number of input boxes a stem needs (highest placeholder index + 1). */
+export declare function countBlanks(segments: FillBlankSegment[]): number;
+/** Placeholder indices present in a stem, ascending and de-duplicated. */
+export declare function extractPlaceholderIndices(text: string): number[];
+/** Normalize one blank's stored value into a list of accepted equivalents. */
+export declare function toAcceptedAnswers(value: unknown): string[];
+/**
+ * Normalize `correct_answer.answers` into `string[][]` padded to `blankCount`.
+ * Accepts the canonical `string[][]` and the legacy flat `string[]`.
+ */
+export declare function normalizeAcceptedAnswers(raw: unknown, blankCount: number): string[][];
+/** Normalize a stored student answer into one string per blank. */
+export declare function toBlankValues(raw: unknown, blankCount: number): string[];
+/** True when the student typed something into at least one blank. */
+export declare function hasAnyBlankValue(raw: unknown): boolean;
+/** Compare a student input against the accepted equivalents of one blank. */
+export declare function isBlankCorrect(value: string, accepted: string[] | undefined): boolean;
+/** Join equivalents for display, e.g. "is / 's". */
+export declare function formatAcceptedAnswers(accepted: string[] | undefined): string;
+/** First equivalent — used to prefill example questions and review hints. */
+export declare function getPrimaryAnswer(accepted: string[] | undefined): string;

package/dist/shared/lib/utils/fill-in-blank.js

@@ -0,0 +1,96 @@
+/**
+ * FILL_IN_BLANK — single source of truth for the whole flow.
+ *
+ * Wire format (never change one side without the other):
+ *   content.question       "A dog {0} swim, but it {1} fly."
+ *   correct_answer.answers string[][] — answers[i] = accepted equivalents for blank {i}
+ *   student answer         { answers: string[] } — one entry per blank, index-aligned
+ *
+ * Matching rule (mirrors the API `normalizeText`): trim, lowercase, collapse inner
+ * whitespace, keep diacritics. A blank is correct when the input equals ANY equivalent.
+ */
+const PLACEHOLDER_PATTERN = /\{(\d+)\}/g;
+/** Split a stem into the text / blank segments used by every renderer. */
+export function parseFillBlankSegments(text) {
+    const segments = [];
+    const regex = new RegExp(PLACEHOLDER_PATTERN);
+    let lastIndex = 0;
+    let match;
+    while ((match = regex.exec(text)) !== null) {
+        if (match.index > lastIndex) {
+            segments.push({ type: 'text', value: text.slice(lastIndex, match.index) });
+        }
+        segments.push({ type: 'blank', index: Number.parseInt(match[1], 10) });
+        lastIndex = regex.lastIndex;
+    }
+    if (lastIndex < text.length) {
+        segments.push({ type: 'text', value: text.slice(lastIndex) });
+    }
+    return segments;
+}
+/**
+ * Renderer-facing parse: like `parseFillBlankSegments`, but guarantees at least
+ * one blank so a stem authored without `{0}` still gets an input box.
+ */
+export function parseFillBlankStem(text) {
+    const segments = parseFillBlankSegments(text);
+    if (!segments.some((segment) => segment.type === 'blank')) {
+        segments.push({ type: 'blank', index: 0 });
+    }
+    return segments;
+}
+/** Number of input boxes a stem needs (highest placeholder index + 1). */
+export function countBlanks(segments) {
+    const highest = segments.reduce((max, segment) => (segment.type === 'blank' ? Math.max(max, segment.index) : max), -1);
+    return highest + 1 || 1;
+}
+/** Placeholder indices present in a stem, ascending and de-duplicated. */
+export function extractPlaceholderIndices(text) {
+    const indices = new Set();
+    for (const segment of parseFillBlankSegments(text || '')) {
+        if (segment.type === 'blank')
+            indices.add(segment.index);
+    }
+    return [...indices].sort((a, b) => a - b);
+}
+/** Normalize one blank's stored value into a list of accepted equivalents. */
+export function toAcceptedAnswers(value) {
+    const list = Array.isArray(value) ? value : [value];
+    return list.map((item) => String(item ?? '').trim()).filter(Boolean);
+}
+/**
+ * Normalize `correct_answer.answers` into `string[][]` padded to `blankCount`.
+ * Accepts the canonical `string[][]` and the legacy flat `string[]`.
+ */
+export function normalizeAcceptedAnswers(raw, blankCount) {
+    const source = Array.isArray(raw) ? raw : [raw];
+    return Array.from({ length: blankCount }, (_, index) => toAcceptedAnswers(source[index]));
+}
+/** Normalize a stored student answer into one string per blank. */
+export function toBlankValues(raw, blankCount) {
+    const source = Array.isArray(raw) ? raw : [raw];
+    return Array.from({ length: blankCount }, (_, index) => String(source[index] ?? ''));
+}
+/** True when the student typed something into at least one blank. */
+export function hasAnyBlankValue(raw) {
+    const source = Array.isArray(raw) ? raw : [raw];
+    return source.some((value) => String(value ?? '').trim().length > 0);
+}
+function normalizeForCompare(value) {
+    return value.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+/** Compare a student input against the accepted equivalents of one blank. */
+export function isBlankCorrect(value, accepted) {
+    const input = normalizeForCompare(value ?? '');
+    if (!input || !accepted?.length)
+        return false;
+    return accepted.some((answer) => normalizeForCompare(answer) === input);
+}
+/** Join equivalents for display, e.g. "is / 's". */
+export function formatAcceptedAnswers(accepted) {
+    return (accepted ?? []).map((answer) => answer.trim()).filter(Boolean).join(' / ');
+}
+/** First equivalent — used to prefill example questions and review hints. */
+export function getPrimaryAnswer(accepted) {
+    return (accepted ?? []).map((answer) => answer.trim()).find(Boolean) || '';
+}

package/dist/shared/lib/utils/question-reverse-transform.js

@@ -66,19 +66,80 @@ const reversePictureChoice = (apiQuestion) => {
 const reverseFillInBlank = (apiQuestion) => {
     const content = asRecord(apiQuestion.content);
     const answer = readAnswer(apiQuestion);
-    const firstBlank = asRecord(asArray(content.blanks)[0]);
+    const toBlankAlts = (value) => {
+        if (Array.isArray(value)) {
+            const cleaned = value
+                .map((item) => (item == null ? '' : String(item).trim()))
+                .filter(Boolean);
+            return cleaned.length > 0 ? cleaned : [''];
+        }
+        if (value == null)
+            return [''];
+        const text = String(value).trim();
+        return text ? [text] : [''];
+    };
+    const toAnswersMatrix = (raw, blankCount) => {
+        let result = [];
+        if (Array.isArray(raw)) {
+            result = raw.map((item) => toBlankAlts(item));
+        }
+        if (typeof blankCount === 'number' && blankCount > 0) {
+            while (result.length < blankCount) {
+                result.push(['']);
+            }
+        }
+        return result;
+    };
+    if (content.question && Array.isArray(answer.answers)) {
+        return {
+            content: '',
+            answer: {
+                question: asString(content.question),
+                answers: toAnswersMatrix(answer.answers),
+                caseSensitive: Boolean(answer.caseSensitive ?? false),
+                imageUrl: asString(content.imageUrl),
+                audioUrl: asString(content.audioUrl),
+                showHints: Boolean(content.showHints ?? false),
+                hints: asArray(content.hints),
+                explanation: asString(apiQuestion.explanation),
+                points: readPoints(apiQuestion),
+            },
+        };
+    }
+    const blanks = asArray(content.blanks);
+    const firstBlank = asRecord(blanks[0]);
+    const answersData = answer.answers ?? {};
+    let answersMatrix = [];
+    if (Array.isArray(answersData)) {
+        answersMatrix = toAnswersMatrix(answersData, blanks.length || undefined);
+    }
+    else if (typeof answersData === 'object' && answersData !== null) {
+        answersMatrix = blanks.map((blank) => toBlankAlts(asRecord(answersData)[asString(asRecord(blank).id)]));
+    }
     return {
         content: '',
         answer: {
             question: asString(content.question ?? firstBlank.text),
-            answers: Array.isArray(answer.answers) ? answer.answers : [],
+            answers: answersMatrix,
             caseSensitive: Boolean(answer.caseSensitive ?? false),
             imageUrl: asString(content.imageUrl),
+            audioUrl: asString(content.audioUrl),
             showHints: Boolean(content.showHints ?? false),
             hints: asArray(content.hints),
             explanation: asString(apiQuestion.explanation),
             points: readPoints(apiQuestion),
-            blanks: asArray(content.blanks),
+            blanks: blanks.map((rawBlank, index) => {
+                const blank = asRecord(rawBlank);
+                const alts = typeof answersData === 'object' && !Array.isArray(answersData)
+                    ? toBlankAlts(asRecord(answersData)[asString(blank.id)])
+                    : answersMatrix[index] || [''];
+                return {
+                    id: blank.id,
+                    text: blank.text,
+                    correctAnswer: alts[0] || '',
+                    correctAnswers: alts,
+                };
+            }),
         },
     };
 };
@@ -181,6 +242,7 @@ const reverseChooseTheCorrectAnswerGroup = (apiQuestion) => {
         });
         const isExample = item.isExample === true;
         const imageUrl = normalizeChooseAnswerGroupImageUrl(itemContent.imageUrl);
+        const audioUrl = asString(itemContent.audioUrl).trim();
         return {
             question: asString(itemContent.question),
             optionType: asString(itemContent.optionType, 'text') === 'image' ? 'image' : 'text',
@@ -194,13 +256,16 @@ const reverseChooseTheCorrectAnswerGroup = (apiQuestion) => {
             points: isExample ? 0 : asNumber(item.points, 1),
             questionNumber: asNumber(item.questionNumber, index + 1),
             ...(imageUrl !== undefined ? { imageUrl } : {}),
+            ...(audioUrl ? { audioUrl } : {}),
         };
     });
+    const audioUrl = asString(asRecord(content.meta).audioUrl).trim();
     return {
         content: '',
         answer: {
             instruction: asString(asRecord(content.meta).instruction, 'Choose the correct answer.'),
             passage: asString(asRecord(content.meta).passage),
+            ...(audioUrl ? { audioUrl } : {}),
             items,
             explanation: asString(apiQuestion.explanation),
             points: items.reduce((total, item) => (item.isExample ? total : total + item.points), 0),

package/dist/shared/types/questions/choose-the-correct-answer-group.d.ts

@@ -8,6 +8,7 @@ export interface ChooseTheCorrectAnswerGroupItemContent {
     options: ChooseTheCorrectAnswerGroupOption[];
     optionType?: 'text' | 'image';
     imageUrl?: string | string[];
+    audioUrl?: string;
 }
 export interface ChooseTheCorrectAnswerGroupItem {
     questionType?: 'CHOOSE_THE_CORRECT_ANSWER';
@@ -23,6 +24,7 @@ export interface ChooseTheCorrectAnswerGroupContent {
     meta?: {
         instruction?: string;
         passage?: string;
+        audioUrl?: string;
     };
     items: ChooseTheCorrectAnswerGroupItem[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinyweb_dev/oe-exam-sdk",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Reusable OceanEdu question components.",
   "type": "module",
   "main": "./dist/index.js",