@tinyweb_dev/oe-exam-sdk 1.0.0 → 1.0.2

package/dist/api/exam-taking.types.d.ts

@@ -52,6 +52,7 @@ export interface ExamTakingTemplatePart {
     sections?: Array<Record<string, unknown>>;
     isGroup?: boolean;
     group?: Record<string, unknown>;
+    suggestedAnswers?: string[];
 }
 export interface ExamTakingQuestionsResult {
     examTemplate?: {

package/dist/components/exams/ExamPreviewDialog.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { CheckCircle2, Eye, GraduationCap } from 'lucide-react';
 import { Button } from '../../components/ui/button';
-import { Dialog, DialogContent, DialogHeader, DialogTitle } from '../../components/ui/dialog';
+import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from '../../components/ui/dialog';
 import { useT } from '../../shared/lib/i18n';
 import { cn } from '../../shared/lib/utils';
 import { ExamPreviewMode } from './exam-preview.mode';
@@ -129,7 +129,9 @@ export function ExamPreviewDialog({ open, onOpenChange, examId, api, title, defa
             scrollToTop();
         }
     };
-    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { className: "max-h-[95vh] max-w-7xl overflow-y-auto", children: [_jsxs(DialogHeader, { className: "flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between border-b pb-3 pr-8", children: [_jsxs(DialogTitle, { className: "flex items-center gap-2 text-lg font-bold", children: [_jsx(Eye, { className: "h-5 w-5 text-blue-600" }), t('admin.exams.preview.title', { name: heading })] }), _jsxs("div", { className: "inline-flex items-center rounded-lg border border-gray-200 bg-gray-100 p-1 shadow-inner", children: [_jsxs("button", { type: "button", onClick: () => setPreviewMode(ExamPreviewMode.STUDENT), className: cn('inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-semibold transition-all', previewMode === ExamPreviewMode.STUDENT
+    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { className: "max-h-[95vh] max-w-7xl overflow-y-auto", children: [_jsxs(DialogHeader, { className: "flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between border-b pb-3 pr-8", children: [_jsxs(DialogTitle, { className: "flex items-center gap-2 text-lg font-bold", children: [_jsx(Eye, { className: "h-5 w-5 text-blue-600" }), t('admin.exams.preview.title', { name: heading })] }), _jsx(DialogDescription, { className: "sr-only", children: previewMode === ExamPreviewMode.ANSWERS
+                                ? t('admin.exams.preview.footerNoteAnswers')
+                                : t('admin.exams.preview.footerNoteStudent') }), _jsxs("div", { className: "inline-flex items-center rounded-lg border border-gray-200 bg-gray-100 p-1 shadow-inner", children: [_jsxs("button", { type: "button", onClick: () => setPreviewMode(ExamPreviewMode.STUDENT), className: cn('inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-semibold transition-all', previewMode === ExamPreviewMode.STUDENT
                                         ? 'bg-white text-blue-700 shadow-sm ring-1 ring-black/5'
                                         : 'text-gray-600 hover:bg-gray-200/70 hover:text-gray-900'), children: [_jsx(GraduationCap, { className: "h-4 w-4" }), _jsx("span", { children: t('admin.exams.preview.mode.student') })] }), _jsxs("button", { type: "button", onClick: () => setPreviewMode(ExamPreviewMode.ANSWERS), className: cn('inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-semibold transition-all', previewMode === ExamPreviewMode.ANSWERS
                                         ? 'bg-emerald-600 text-white shadow-sm'

package/dist/components/exams/take/components/QuestionRenderer.js

@@ -42,8 +42,8 @@ export function QuestionRenderer({ part, answers, onAnswerChange, isReviewMode =
     };
     switch (questionType) {
         case 'FILL_IN_BLANK': {
-            const data = transformFillInBlank(questions);
-            return (_jsx(MoversListenAndWriteRenderer, { partNumber: partNo, partName: part.name, questionCount: questionCount, instruction: part.instructions || data.instruction, title: data.title, imageUrl: data.groupImageUrl || data.imageUrl, audioUrl: data.audioUrl || part.audioUrl, exampleText: data.exampleText, exampleHighlight: data.exampleHighlight, questions: getRenderQuestions(data.questions), answers: answers, onAnswerChange: onAnswerChange, isReviewMode: isReviewMode, showHints: data.showHints, groupContent: data.groupContent, groupTitle: data.groupTitle }));
+            const data = transformFillInBlank(questions, { suggestedAnswers: part.suggestedAnswers });
+            return (_jsx(MoversListenAndWriteRenderer, { partNumber: partNo, partName: part.name, questionCount: questionCount, instruction: part.instructions || data.instruction, title: data.title, imageUrl: data.groupImageUrl || data.imageUrl, audioUrl: data.audioUrl || part.audioUrl, exampleText: data.exampleText, exampleHighlight: data.exampleHighlight, questions: getRenderQuestions(data.questions), answers: answers, onAnswerChange: onAnswerChange, isReviewMode: isReviewMode, showHints: data.showHints, groupContent: data.groupContent, groupTitle: data.groupTitle, imageLabels: data.imageLabels }));
         }
         case 'WRITE_CORRECT_VERB_FORM': {
             const data = transformWriteCorrectVerbForm(questions);

package/dist/components/exams/take/components/question-renderers/MoversListenAndWriteRenderer.d.ts

@@ -1,4 +1,5 @@
 import type { FillBlankQuestion } from '../../types';
+import { type ImageLabelData } from '../../../../questions/_shared/types/question-group.type';
 interface MoversListenAndWriteRendererProps {
     partNumber: number;
     partName?: string;
@@ -16,6 +17,7 @@ interface MoversListenAndWriteRendererProps {
     showHints?: boolean;
     groupContent?: string;
     groupTitle?: string;
+    imageLabels?: ImageLabelData[];
 }
-export declare function MoversListenAndWriteRenderer({ partNumber, partName, questionCount, instruction, imageUrl, audioUrl, title, exampleText, exampleHighlight, questions, answers, onAnswerChange, isReviewMode, showHints, groupContent, groupTitle, }: MoversListenAndWriteRendererProps): import("react").JSX.Element;
+export declare function MoversListenAndWriteRenderer({ partNumber, partName, questionCount, instruction, imageUrl, audioUrl, title, exampleText, exampleHighlight, questions, answers, onAnswerChange, isReviewMode, showHints, groupContent, groupTitle, imageLabels, }: MoversListenAndWriteRendererProps): import("react").JSX.Element;
 export {};

package/dist/components/exams/take/components/question-renderers/MoversListenAndWriteRenderer.js

@@ -6,6 +6,8 @@ import CambridgeYleInstructionBanner from '../../../../../components/themes/camb
 import CambridgeYleAudioPlayer from '../../../../../components/themes/cambridge-yle/CambridgeYleAudioPlayer';
 import CambridgeYleExampleText from '../../../../../components/themes/cambridge-yle/CambridgeYleExampleText';
 import { countBlanks, formatAcceptedAnswers, getPrimaryAnswer, isBlankCorrect, toBlankValues, } from '../../../../../shared/lib/utils/fill-in-blank';
+import { ImageLabelWordBank } from '../../../../questions/groups/ImageLabelWordBank';
+import { hasImageLabels } from '../../../../questions/_shared/types/question-group.type';
 /** Preserve author newlines in fill-blank stems by mapping `\n` → `<br />`. */
 function renderTextWithLineBreaks(text) {
     const lines = text.split('\n');
@@ -23,9 +25,10 @@ function blankInputClassName({ isExampleQ, isReviewMode, isCorrect, isWrong, })
     }
     return 'border-blue-200 bg-blue-50/30 text-blue-900 focus:border-blue-500 focus:bg-white focus:ring-4 focus:ring-blue-100';
 }
-export function MoversListenAndWriteRenderer({ partNumber, partName, questionCount, instruction, imageUrl, audioUrl, title, exampleText, exampleHighlight, questions, answers, onAnswerChange, isReviewMode = false, showHints = false, groupContent, groupTitle, }) {
+export function MoversListenAndWriteRenderer({ partNumber, partName, questionCount, instruction, imageUrl, audioUrl, title, exampleText, exampleHighlight, questions, answers, onAnswerChange, isReviewMode = false, showHints = false, groupContent, groupTitle, imageLabels, }) {
+    const hasImageLabelBank = hasImageLabels(imageLabels);
     const hasGroupContent = !!(audioUrl || imageUrl || groupContent || exampleText);
-    return (_jsxs("div", { className: "flex flex-col h-full gap-4 sm:gap-6 overflow-y-auto custom-scrollbar relative", children: [_jsxs("div", { className: "flex flex-col gap-2 sm:gap-3 p-3 sm:px-6 sm:pt-4", children: [_jsx(CambridgeYlePartBanner, { partNumber: partNumber, questionCount: questionCount, partName: partName, isReviewMode: isReviewMode }), _jsx(CambridgeYleInstructionBanner, { instruction: instruction, hasExample: !!exampleText, isReviewMode: isReviewMode })] }), hasGroupContent && (_jsxs("div", { className: "flex flex-col gap-2 sm:gap-3 p-3 sm:px-6 sm:pt-0 sticky top-0 z-20 bg-white/95 backdrop-blur pb-2 shadow-sm border-b border-gray-100", children: [audioUrl && _jsx(CambridgeYleAudioPlayer, { audioSrc: audioUrl, compact: true }), _jsxs("div", { className: "max-h-[35vh] overflow-y-auto custom-scrollbar pr-2 flex flex-col gap-3", children: [imageUrl && (_jsx("div", { className: "flex items-center justify-center", children: _jsx(ResolvedImage, { src: imageUrl, alt: "Shared illustration", className: "max-h-[200px] rounded-lg object-contain shadow-md" }) })), groupContent && (_jsxs("div", { className: "rounded-lg bg-amber-50 p-3 text-sm leading-relaxed text-gray-700 shadow-inner", children: [groupTitle && _jsx("h3", { className: "mb-2 font-semibold text-gray-800", children: groupTitle }), groupContent] }))] }), exampleText && (_jsx(CambridgeYleExampleText, { text: exampleText, highlightedWord: exampleHighlight || '' }))] })), _jsxs("div", { className: "flex flex-col gap-4 p-3 sm:gap-6 sm:pb-6 sm:px-6", children: [title && (_jsx("h2", { className: "text-center text-3xl font-bold uppercase text-coral-500", children: title })), _jsx("div", { className: "flex flex-col gap-6 sm:gap-8", children: questions.map((question) => {
+    return (_jsxs("div", { className: "flex flex-col h-full gap-4 sm:gap-6 overflow-y-auto custom-scrollbar relative", children: [_jsxs("div", { className: "flex flex-col gap-2 sm:gap-3 p-3 sm:px-6 sm:pt-4", children: [_jsx(CambridgeYlePartBanner, { partNumber: partNumber, questionCount: questionCount, partName: partName, isReviewMode: isReviewMode }), _jsx(CambridgeYleInstructionBanner, { instruction: instruction, hasExample: !!exampleText, isReviewMode: isReviewMode }), hasImageLabelBank && (_jsx(ImageLabelWordBank, { items: imageLabels, className: "rounded-2xl border border-slate-200 bg-slate-50/80 p-4 shadow-sm" }))] }), hasGroupContent && (_jsxs("div", { className: "flex flex-col gap-2 sm:gap-3 p-3 sm:px-6 sm:pt-0 sticky top-0 z-20 bg-white/95 backdrop-blur pb-2 shadow-sm border-b border-gray-100", children: [audioUrl && _jsx(CambridgeYleAudioPlayer, { audioSrc: audioUrl, compact: true }), _jsxs("div", { className: "max-h-[35vh] overflow-y-auto custom-scrollbar pr-2 flex flex-col gap-3", children: [imageUrl && (_jsx("div", { className: "flex items-center justify-center", children: _jsx(ResolvedImage, { src: imageUrl, alt: "Shared illustration", className: "max-h-[200px] rounded-lg object-contain shadow-md" }) })), groupContent && (_jsxs("div", { className: "rounded-lg bg-amber-50 p-3 text-sm leading-relaxed text-gray-700 shadow-inner", children: [groupTitle && _jsx("h3", { className: "mb-2 font-semibold text-gray-800", children: groupTitle }), groupContent] }))] }), exampleText && (_jsx(CambridgeYleExampleText, { text: exampleText, highlightedWord: exampleHighlight || '' }))] })), _jsxs("div", { className: "flex flex-col gap-4 p-3 sm:gap-6 sm:pb-6 sm:px-6", children: [title && (_jsx("h2", { className: "text-center text-3xl font-bold uppercase text-coral-500", children: title })), _jsx("div", { className: "flex flex-col gap-6 sm:gap-8", children: questions.map((question) => {
                             const isExampleQ = question.isExample || false;
                             const isDisabled = isReviewMode || isExampleQ;
                             const blankCount = countBlanks(question.segments);

package/dist/components/exams/take/components/question-renderers/MoversWordFillStructuredFormRenderer.js

@@ -6,6 +6,7 @@ import CambridgeYlePartBanner from '../../../../../components/themes/cambridge-y
 import CambridgeYleInstructionBanner from '../../../../../components/themes/cambridge-yle/CambridgeYleInstructionBanner';
 import CambridgeYleAudioPlayer from '../../../../../components/themes/cambridge-yle/CambridgeYleAudioPlayer';
 import { cn } from '../../../../../shared/lib/utils';
+import { expandWfsfCorrectAlts, formatWfsfCorrectLabel, isWfsfBlankCorrect, } from '../../../../../shared/lib/utils/wfsf-blank-match';
 /**
  * Replace `{key}` placeholders with inline blank controls.
  * WITH_OPTIONS blanks become <select>; free-type stay <input>.
@@ -51,14 +52,6 @@ function buildHtmlWithInputPlaceholders(html, wordBank) {
     `;
     });
 }
-function normalizeStructuredAnswer(value, caseSensitive) {
-    const normalized = value
-        .trim()
-        .replace(/[\p{P}]/gu, '')
-        .replace(/\s+/g, ' ')
-        .trim();
-    return caseSensitive ? normalized : normalized.toLowerCase();
-}
 // Stable empty object to avoid new {} on every render (breaks React.memo)
 const emptyObj = {};
 /**
@@ -96,33 +89,33 @@ const StructuredFormQuestion = memo(function StructuredFormQuestion({ question,
             const wrapper = container.querySelector(`[data-blank-wrapper="${key}"]`);
             const hint = container.querySelector(`[data-blank-hint="${key}"]`);
             const userAnswer = initialAnswersRef.current[key] || '';
-            const correctAnswer = question.answers[key] || '';
+            const correctAnswer = question.answers[key];
+            const correctLabel = formatWfsfCorrectLabel(correctAnswer);
             const hasUserAnswer = userAnswer.trim().length > 0;
             const isCorrect = hasUserAnswer
-                && normalizeStructuredAnswer(userAnswer, question.caseSensitive)
-                    === normalizeStructuredAnswer(correctAnswer, question.caseSensitive);
+                && isWfsfBlankCorrect(userAnswer, correctAnswer, question.caseSensitive);
             // Restore saved answer value on mount
-            const shouldReplaceInputWithReviewText = isReviewMode && !isCorrect && correctAnswer.trim().length > 0;
+            const shouldReplaceInputWithReviewText = isReviewMode && !isCorrect && correctLabel.length > 0;
             input.value = shouldReplaceInputWithReviewText
-                ? `${hasUserAnswer ? userAnswer : '(trống)'} → ${correctAnswer}`
+                ? `${hasUserAnswer ? userAnswer : '(trống)'} → ${correctLabel}`
                 : userAnswer;
             input.disabled = isReviewMode;
             const isSelect = input.tagName === 'SELECT';
             // Set classes from blankStyle (letter = square box)
             const blankStyle = question.blankStyle || 'word';
             const isLetter = blankStyle === 'letter';
-            const isPhrase = blankStyle === 'phrase';
+            const isPhrase = blankStyle === 'phrase' || blankStyle === 'translate';
             if (isLetter && !isSelect && 'maxLength' in input) {
-                input.maxLength = Math.max(1, (correctAnswer || ' ').trim().length || 1);
+                const maxAltLen = expandWfsfCorrectAlts(correctAnswer).reduce((max, alt) => Math.max(max, alt.trim().length), 0);
+                input.maxLength = Math.max(1, maxAltLen || 1);
             }
             input.className = cn('structured-blank-input inline-block bg-slate-50/40 text-sm font-semibold outline-none transition-all align-baseline hover:bg-slate-100/60 focus:bg-teal-50/60 focus:ring-0', isSelect
                 ? 'min-w-[5.5rem] max-w-[10rem] rounded border px-2 py-1 text-center'
                 : isLetter
                     ? 'h-7 w-7 rounded border-2 px-0 text-center uppercase'
                     : isPhrase
-                        ? 'min-w-[9rem] max-w-[18rem] w-[14ch] rounded-t border-b-2 px-2 py-0.5 text-center'
-                        : // blankStyle=word — short single-token field
-                            'min-w-[4.5rem] max-w-[7.5rem] w-[8ch] rounded-t border-b-2 px-1 py-0.5 text-center', isReviewMode
+                        ? 'min-w-[16rem] max-w-[36rem] w-[28ch] rounded-t border-b-2 px-2 py-0.5 text-center'
+                        : 'min-w-[4.5rem] max-w-[8rem] w-[10ch] rounded-t border-b-2 px-1 py-0.5 text-center', isReviewMode
                 ? isCorrect
                     ? 'border-emerald-500 bg-emerald-50 text-emerald-800 font-bold'
                     : hasUserAnswer
@@ -130,7 +123,7 @@ const StructuredFormQuestion = memo(function StructuredFormQuestion({ question,
                         : 'border-amber-500 bg-amber-50 text-amber-800 font-bold'
                 : 'border-slate-400 text-slate-800 focus:border-teal-600');
             if (!isSelect && !isLetter && 'size' in input) {
-                input.size = isPhrase ? 18 : 10;
+                input.size = isPhrase ? 28 : 10;
             }
             // letter inline box — host FE may not scan Tailwind h-7/w-7
             if (isLetter) {
@@ -174,7 +167,7 @@ const StructuredFormQuestion = memo(function StructuredFormQuestion({ question,
     }, [processedHtml, isReviewMode]);
     return (_jsxs("div", { className: "space-y-3", children: [question.title && (_jsx("h3", { className: "text-base font-semibold text-gray-800", children: question.title })), question.imageUrl && (_jsx("div", { className: "flex justify-center", children: _jsx("div", { className: "overflow-hidden rounded-lg border border-gray-200", children: _jsx(ResolvedImage, { src: question.imageUrl, alt: question.title || 'Question image', className: "max-h-48 w-auto object-contain" }) }) })), _jsx("div", { ref: containerRef, className: cn('structured-form-content rounded-lg border border-gray-200 bg-gradient-to-r from-gray-50 to-slate-50 p-4 text-sm leading-relaxed text-gray-800', '[&_.structured-blank-wrapper]:inline-flex [&_.structured-blank-wrapper]:align-baseline [&_.structured-blank-wrapper]:items-baseline [&_.structured-blank-hint]:max-w-[180px]', 
                 // Conversation: speaker column hug name (not equal 50/50 split)
-                '[&_table.dialogue]:w-full [&_table.dialogue]:border-collapse [&_table.dialogue]:table-fixed', '[&_table.dialogue_td.speaker]:w-[1%] [&_table.dialogue_td.speaker]:whitespace-nowrap', '[&_table.dialogue_td.speaker]:align-top [&_table.dialogue_td.speaker]:pr-3', '[&_table.dialogue_td.speaker]:font-semibold [&_table.dialogue_td.speaker]:text-slate-900', '[&_table.dialogue_td]:align-top [&_table.dialogue_td]:py-1.5') }), isReviewMode && (_jsxs("div", { className: "space-y-2 rounded-lg border border-slate-200 bg-slate-50 p-3", children: [_jsxs("div", { className: "flex flex-wrap gap-2 text-[11px] font-medium", children: [_jsxs("span", { className: "inline-flex items-center gap-1 rounded-full bg-green-100 px-2 py-1 text-green-700", children: [_jsx("span", { className: "h-2 w-2 rounded-full bg-green-500" }), "\u0110\u00FAng"] }), _jsxs("span", { className: "inline-flex items-center gap-1 rounded-full bg-red-100 px-2 py-1 text-red-700", children: [_jsx("span", { className: "h-2 w-2 rounded-full bg-red-500" }), "Sai"] }), _jsxs("span", { className: "inline-flex items-center gap-1 rounded-full bg-amber-100 px-2 py-1 text-amber-700", children: [_jsx("span", { className: "h-2 w-2 rounded-full bg-amber-500" }), "Ch\u01B0a tr\u1EA3 l\u1EDDi"] })] }), _jsxs("div", { children: [_jsx("span", { className: "text-[10px] font-medium uppercase tracking-wider text-slate-500", children: "\u0110\u00E1p \u00E1n \u0111\u00FAng" }), _jsx("div", { className: "mt-1 flex flex-wrap gap-1.5", children: Object.entries(question.answers).map(([key, val]) => (_jsxs("span", { className: "rounded border border-green-300 bg-green-100 px-2 py-0.5 text-xs font-semibold text-green-800", children: [key, ": ", val] }, key))) })] })] }))] }));
+                '[&_table.dialogue]:w-full [&_table.dialogue]:border-collapse [&_table.dialogue]:table-fixed', '[&_table.dialogue_td.speaker]:w-[1%] [&_table.dialogue_td.speaker]:whitespace-nowrap', '[&_table.dialogue_td.speaker]:align-top [&_table.dialogue_td.speaker]:pr-3', '[&_table.dialogue_td.speaker]:font-semibold [&_table.dialogue_td.speaker]:text-slate-900', '[&_table.dialogue_td]:align-top [&_table.dialogue_td]:py-1.5') }), isReviewMode && (_jsxs("div", { className: "space-y-2 rounded-lg border border-slate-200 bg-slate-50 p-3", children: [_jsxs("div", { className: "flex flex-wrap gap-2 text-[11px] font-medium", children: [_jsxs("span", { className: "inline-flex items-center gap-1 rounded-full bg-green-100 px-2 py-1 text-green-700", children: [_jsx("span", { className: "h-2 w-2 rounded-full bg-green-500" }), "\u0110\u00FAng"] }), _jsxs("span", { className: "inline-flex items-center gap-1 rounded-full bg-red-100 px-2 py-1 text-red-700", children: [_jsx("span", { className: "h-2 w-2 rounded-full bg-red-500" }), "Sai"] }), _jsxs("span", { className: "inline-flex items-center gap-1 rounded-full bg-amber-100 px-2 py-1 text-amber-700", children: [_jsx("span", { className: "h-2 w-2 rounded-full bg-amber-500" }), "Ch\u01B0a tr\u1EA3 l\u1EDDi"] })] }), _jsxs("div", { children: [_jsx("span", { className: "text-[10px] font-medium uppercase tracking-wider text-slate-500", children: "\u0110\u00E1p \u00E1n \u0111\u00FAng" }), _jsx("div", { className: "mt-1 flex flex-wrap gap-1.5", children: Object.entries(question.answers).map(([key, val]) => (_jsxs("span", { className: "rounded border border-green-300 bg-green-100 px-2 py-0.5 text-xs font-semibold text-green-800", children: [key, ": ", formatWfsfCorrectLabel(val)] }, key))) })] })] }))] }));
 });
 export function MoversWordFillStructuredFormRenderer({ partNumber, partName, questionCount, instruction, audioUrl, groupTitle, groupContent, groupImageUrl, questions, answers, onAnswerChange, isReviewMode = false, }) {
     const answersRef = useRef(answers);

package/dist/components/exams/take/exam-taking.utils.d.ts

@@ -11,7 +11,7 @@ export interface TemplateSection {
     viewMode?: string;
     wordBankConfig?: string[];
 }
-export type WfsfBlankStyle = 'letter' | 'word' | 'phrase';
+export type WfsfBlankStyle = 'letter' | 'word' | 'phrase' | 'translate';
 export type WfsfWordBankEntry = {
     options: string[];
 } | {
@@ -21,7 +21,7 @@ export type WfsfWordBankEntry = {
 export interface WordFillStructuredFormQuestion {
     id: string;
     content: string;
-    answers: Record<string, string>;
+    answers: Record<string, string | string[]>;
     title?: string;
     instruction?: string;
     caseSensitive?: boolean;
@@ -48,6 +48,7 @@ export interface ExamTakingPart {
     wordBankConfig?: string[];
     startIndex?: number;
     endIndex?: number;
+    suggestedAnswers?: string[];
 }
 export declare function unwrap<T>(value: ApiData<T> | T): T;
 export declare function unwrapAttempt(value: ExamTakingAttempt | {

package/dist/components/exams/take/exam-taking.utils.js

@@ -28,6 +28,7 @@ export function groupQuestions(result) {
             viewMode: typeof template?.group?.viewMode === 'string' ? template.group.viewMode : undefined,
             startIndex: template?.startIndex,
             endIndex: template?.endIndex,
+            suggestedAnswers: template?.suggestedAnswers,
             questions: questions.sort((a, b) => a.question_number - b.question_number),
         };
     });
@@ -117,6 +118,8 @@ export function transformWordFillStructuredForm(questions) {
             return 'letter';
         if (v === 'phrase' || v === 'sentence')
             return 'phrase';
+        if (v === 'translate')
+            return 'translate';
         return 'word';
     };
     const normalizeWordBank = (raw) => {

package/dist/components/exams/take/utils/question-transformers.d.ts

@@ -63,6 +63,7 @@ export interface QuestionPart {
     /** Zero-based exam-order start index of this part/section (for question numbering). */
     startIndex?: number;
     endIndex?: number;
+    suggestedAnswers?: string[];
 }
 /** Nested template group payload ({ items, config, type }) from the API template. */
 export interface TemplateGroupConfig {
@@ -108,6 +109,7 @@ export interface TemplatePart {
     category?: string;
     /** Max points for this part from exams.template.parts */
     points?: number;
+    suggestedAnswers?: string[];
 }
 /**
  * Group questions by part_id AND questionGroup.id
@@ -122,7 +124,9 @@ export interface TemplatePart {
  * @param templateParts - Optional template parts with name/instructions metadata
  */
 export declare function groupQuestionsByPart(questions: ApiQuestion[], templateParts?: TemplatePart[]): QuestionPart[];
-export declare function transformFillInBlank(questions: ApiQuestion[]): {
+export declare function transformFillInBlank(questions: ApiQuestion[], options?: {
+    suggestedAnswers?: string[];
+}): {
     questions: FillBlankQuestion[];
     title: string;
     imageUrl?: string;
@@ -134,6 +138,10 @@ export declare function transformFillInBlank(questions: ApiQuestion[]): {
     groupContent?: string;
     groupTitle?: string;
     groupImageUrl?: string;
+    imageLabels?: Array<{
+        imageUrl: string;
+        label: string;
+    }>;
 };
 export declare function transformWriteCorrectVerbForm(questions: ApiQuestion[]): {
     questions: FillBlankQuestion[];
@@ -387,7 +395,7 @@ export declare function transformWriteSentences(questions: ApiQuestion[]): {
     title?: string;
     groupContent?: string;
 };
-export type WfsfBlankStyle = 'letter' | 'word' | 'phrase';
+export type WfsfBlankStyle = 'letter' | 'word' | 'phrase' | 'translate';
 export type WfsfWordBankEntry = {
     options: string[];
 } | {
@@ -400,7 +408,7 @@ export interface WordFillStructuredFormQuestion {
     title: string;
     imageUrl?: string;
     content: string;
-    answers: Record<string, string>;
+    answers: Record<string, string | string[]>;
     caseSensitive: boolean;
     /** letter = square boxes; word / phrase = underline width */
     blankStyle: WfsfBlankStyle;

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

@@ -41,7 +41,9 @@ export function groupQuestionsByPart(questions, templateParts) {
         // a single screen with the passage on the left and ALL questions on the
         // right — so keep it whole and pass the sections through for the renderer.
         const partLevelGroup = templatePart?.group;
-        const hasDocumentGroup = Boolean(templatePart?.isGroup) && partLevelGroup?.type === 'DOCUMENT';
+        const sharedGroupType = String(partLevelGroup?.type || '').toUpperCase();
+        const hasDocumentGroup = Boolean(templatePart?.isGroup) &&
+            (sharedGroupType === 'DOCUMENT' || sharedGroupType === 'IMAGE_LABEL' || sharedGroupType === 'ARTICLES');
         // Mixed multi-section part (e.g. Listening SECTION 2: CHOOSE + MATCH +
         // WORD_FILL): keep it whole and pass the sections through so the grouped
         // renderer can stack each sub-section on one screen. Without this the part
@@ -68,6 +70,7 @@ export function groupQuestionsByPart(questions, templateParts) {
                 sections: templatePart?.sections,
                 startIndex: templatePart?.startIndex,
                 endIndex: templatePart?.endIndex,
+                suggestedAnswers: templatePart?.suggestedAnswers,
             });
             continue;
         }
@@ -96,6 +99,7 @@ export function groupQuestionsByPart(questions, templateParts) {
                 group: templatePart?.group,
                 startIndex: templatePart?.startIndex,
                 endIndex: templatePart?.endIndex,
+                suggestedAnswers: templatePart?.suggestedAnswers,
             });
             continue;
         }
@@ -138,6 +142,7 @@ export function groupQuestionsByPart(questions, templateParts) {
                 group: section.group,
                 startIndex: section.startIndex,
                 endIndex: section.endIndex,
+                suggestedAnswers: section.suggestedAnswers ?? templatePart?.suggestedAnswers,
             });
         }
     }
@@ -150,7 +155,42 @@ export function groupQuestionsByPart(questions, templateParts) {
         return (a.questions[0]?.question_number || 0) - (b.questions[0]?.question_number || 0);
     });
 }
-export function transformFillInBlank(questions) {
+// ============================================
+// FILL_IN_BLANK Transformer
+// ============================================
+function asImageLabelItems(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const items = value
+        .map((item) => {
+        if (!item || typeof item !== 'object')
+            return null;
+        const imageUrl = String(item.imageUrl ?? '').trim();
+        const label = String(item.label ?? '').trim();
+        if (!imageUrl && !label)
+            return null;
+        return { imageUrl, label };
+    })
+        .filter((item) => item !== null);
+    return items.length > 0 ? items : undefined;
+}
+function collectFillInBlankImageLabels(questions, suggestedAnswers) {
+    for (const question of questions) {
+        const payload = question.questionGroup?.payload ||
+            question.question_group?.payload;
+        const fromGroup = asImageLabelItems(payload?.imageLabels);
+        if (fromGroup)
+            return fromGroup;
+        const fromContent = asImageLabelItems(question.content?.imageLabels);
+        if (fromContent)
+            return fromContent;
+    }
+    if (suggestedAnswers?.length) {
+        return suggestedAnswers.map((label) => ({ imageUrl: '', label: String(label) }));
+    }
+    return undefined;
+}
+export function transformFillInBlank(questions, options) {
     const firstQuestion = questions[0];
     const content = firstQuestion?.content;
     const groupPayload = firstQuestion?.questionGroup?.payload;
@@ -187,6 +227,7 @@ export function transformFillInBlank(questions) {
         groupContent: groupPayload?.content || groupPayload?.groupContent,
         groupTitle: groupPayload?.title,
         groupImageUrl: groupPayload?.mainImageUrl || groupPayload?.imageUrl,
+        imageLabels: collectFillInBlankImageLabels(questions, options?.suggestedAnswers),
     };
 }
 export function transformWriteCorrectVerbForm(questions) {
@@ -1168,6 +1209,8 @@ function normalizeWfsfBlankStyle(raw) {
         return 'letter';
     if (v === 'phrase' || v === 'sentence')
         return 'phrase';
+    if (v === 'translate')
+        return 'translate';
     return 'word';
 }
 function normalizeWfsfWordBank(raw) {

package/dist/components/questions/_shared/hooks/useBasicQuestionGroup.d.ts

@@ -1,4 +1,4 @@
-import type { QuestionGroupConfig, BasicGroupData, ArticleData } from '../types/question-group.type';
+import type { QuestionGroupConfig, BasicGroupData, ArticleData, ImageLabelData } from '../types/question-group.type';
 /**
  * Derives which group number a question at `questionIndexInPart` belongs to,
  * given the part's group configuration array.
@@ -23,6 +23,8 @@ export interface UseBasicQuestionGroupOptions {
     initialData?: BasicGroupData;
     /** Number of articles for ARTICLES group type (creates empty articles array when > 0) */
     articleCount?: number;
+    /** Number of image+label items for IMAGE_LABEL group type */
+    imageLabelCount?: number;
 }
 export interface UseBasicQuestionGroupReturn {
     /** Is this question part of a group (i.e. groups array is non-empty)? */
@@ -36,11 +38,13 @@ export interface UseBasicQuestionGroupReturn {
     groupContent: string;
     imageUrl: string;
     articles: ArticleData[];
+    imageLabels: ImageLabelData[];
     setGroupTitle: (value: string) => void;
     setGroupSubtitle: (value: string) => void;
     setGroupContent: (value: string) => void;
     setImageUrl: (value: string) => void;
     setArticles: (articles: ArticleData[]) => void;
+    setImageLabels: (imageLabels: ImageLabelData[]) => void;
 }
 /**
  * `useBasicQuestionGroup`
@@ -53,4 +57,4 @@ export interface UseBasicQuestionGroupReturn {
  * the same group), falls back to `initialData`, and writes every change back to
  * the store so sibling questions instantly see the updated values.
  */
-export declare function useBasicQuestionGroup({ partId, groups, questionIndexInPart, initialData, articleCount, }: UseBasicQuestionGroupOptions): UseBasicQuestionGroupReturn;
+export declare function useBasicQuestionGroup({ partId, groups, questionIndexInPart, initialData, articleCount, imageLabelCount, }: UseBasicQuestionGroupOptions): UseBasicQuestionGroupReturn;

package/dist/components/questions/_shared/hooks/useBasicQuestionGroup.js

@@ -54,7 +54,7 @@ export function getIsFirstInGroup(questionIndexInPart, groups) {
  * the same group), falls back to `initialData`, and writes every change back to
  * the store so sibling questions instantly see the updated values.
  */
-export function useBasicQuestionGroup({ partId, groups, questionIndexInPart, initialData, articleCount = 0, }) {
+export function useBasicQuestionGroup({ partId, groups, questionIndexInPart, initialData, articleCount = 0, imageLabelCount = 0, }) {
     const setSharedPassageData = useExamQuestionStore((s) => s.setSharedPassageData);
     const getSharedPassageData = useExamQuestionStore((s) => s.getSharedPassageData);
     const isGrouped = Boolean(groups && groups.length > 0);
@@ -67,6 +67,9 @@ export function useBasicQuestionGroup({ partId, groups, questionIndexInPart, ini
     const defaultArticles = articleCount > 0
         ? Array.from({ length: articleCount }, () => ({ name: '', content: '', imageUrl: '' }))
         : [];
+    const defaultImageLabels = imageLabelCount > 0
+        ? Array.from({ length: imageLabelCount }, () => ({ imageUrl: '', label: '' }))
+        : [];
     const resolveInitial = () => {
         if (isGrouped && partId) {
             const stored = getSharedPassageData(partId, currentGroupNumber);
@@ -77,6 +80,7 @@ export function useBasicQuestionGroup({ partId, groups, questionIndexInPart, ini
                     content: stored.groupContent ?? stored.passage ?? initialData?.content ?? '',
                     imageUrl: stored.imageUrl ?? initialData?.imageUrl ?? '',
                     articles: stored.articles ?? initialData?.articles ?? defaultArticles,
+                    imageLabels: stored.imageLabels ?? initialData?.imageLabels ?? defaultImageLabels,
                 };
             }
         }
@@ -86,6 +90,7 @@ export function useBasicQuestionGroup({ partId, groups, questionIndexInPart, ini
             content: initialData?.content ?? '',
             imageUrl: initialData?.imageUrl ?? '',
             articles: initialData?.articles ?? defaultArticles,
+            imageLabels: initialData?.imageLabels ?? defaultImageLabels,
         };
     };
     const initial = resolveInitial();
@@ -94,6 +99,7 @@ export function useBasicQuestionGroup({ partId, groups, questionIndexInPart, ini
     const [groupContent, setGroupContentState] = useState(initial.content ?? '');
     const [imageUrl, setImageUrlState] = useState(initial.imageUrl ?? '');
     const [articles, setArticlesState] = useState(initial.articles ?? defaultArticles);
+    const [imageLabels, setImageLabelsState] = useState(initial.imageLabels ?? defaultImageLabels);
     // Track the last rendered group number so we can re-sync when navigating
     const prevGroupNumberRef = useRef(currentGroupNumber);
     // Track whether we have already seeded from initialData for the current group
@@ -121,7 +127,8 @@ export function useBasicQuestionGroup({ partId, groups, questionIndexInPart, ini
         const newContent = initialData.content || null;
         const newImage = initialData.imageUrl || null;
         const newArticles = initialData.articles || null;
-        if (newTitle === null && newSubtitle === null && newContent === null && newImage === null && newArticles === null)
+        const newImageLabels = initialData.imageLabels || null;
+        if (newTitle === null && newSubtitle === null && newContent === null && newImage === null && newArticles === null && newImageLabels === null)
             return;
         if (newTitle !== null)
             setGroupTitleState(newTitle);
@@ -133,6 +140,8 @@ export function useBasicQuestionGroup({ partId, groups, questionIndexInPart, ini
             setImageUrlState(newImage);
         if (newArticles !== null)
             setArticlesState(newArticles);
+        if (newImageLabels !== null)
+            setImageLabelsState(newImageLabels);
         setSharedPassageData(partId, currentGroupNumber, {
             passageTitle: newTitle ?? '',
             passageSubtitle: newSubtitle ?? '',
@@ -140,6 +149,7 @@ export function useBasicQuestionGroup({ partId, groups, questionIndexInPart, ini
             passage: newContent ?? '',
             imageUrl: newImage ?? '',
             articles: newArticles ?? defaultArticles,
+            imageLabels: newImageLabels ?? defaultImageLabels,
         });
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [initialData, partId, currentGroupNumber, isGrouped]);
@@ -153,12 +163,13 @@ export function useBasicQuestionGroup({ partId, groups, questionIndexInPart, ini
         if (!isGrouped || !partId)
             return;
         const stored = getSharedPassageData(partId, currentGroupNumber);
-        if (stored && (stored.passageTitle || stored.passageSubtitle || stored.groupContent || stored.passage || stored.imageUrl || stored.articles)) {
+        if (stored && (stored.passageTitle || stored.passageSubtitle || stored.groupContent || stored.passage || stored.imageUrl || stored.articles || stored.imageLabels)) {
             setGroupTitleState(stored.passageTitle ?? '');
             setGroupSubtitleState(stored.passageSubtitle ?? '');
             setGroupContentState(stored.groupContent ?? stored.passage ?? '');
             setImageUrlState(stored.imageUrl ?? '');
             setArticlesState(stored.articles ?? defaultArticles);
+            setImageLabelsState(stored.imageLabels ?? defaultImageLabels);
         }
         else {
             setGroupTitleState(initialData?.title ?? '');
@@ -166,22 +177,26 @@ export function useBasicQuestionGroup({ partId, groups, questionIndexInPart, ini
             setGroupContentState(initialData?.content ?? '');
             setImageUrlState(initialData?.imageUrl ?? '');
             setArticlesState(initialData?.articles ?? defaultArticles);
+            setImageLabelsState(initialData?.imageLabels ?? defaultImageLabels);
         }
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [currentGroupNumber, partId, isGrouped]);
     // ------------------------------------------------------------------
     // Helpers: write state + persist to store
     // ------------------------------------------------------------------
-    const persistToStore = (title, subtitle, content, image, arts) => {
+    const persistToStore = (title, subtitle, content, image, arts, labels) => {
         if (!isGrouped || !partId)
             return;
+        const existing = getSharedPassageData(partId, currentGroupNumber);
         setSharedPassageData(partId, currentGroupNumber, {
+            ...existing,
             passageTitle: title,
             passageSubtitle: subtitle,
             groupContent: content,
             passage: content,
             imageUrl: image,
             articles: arts ?? articles,
+            imageLabels: labels ?? imageLabels,
         });
     };
     const setGroupTitle = (value) => {
@@ -202,7 +217,11 @@ export function useBasicQuestionGroup({ partId, groups, questionIndexInPart, ini
     };
     const setArticles = (value) => {
         setArticlesState(value);
-        persistToStore(groupTitle, groupSubtitle, groupContent, imageUrl, value);
+        persistToStore(groupTitle, groupSubtitle, groupContent, imageUrl, value, imageLabels);
+    };
+    const setImageLabels = (value) => {
+        setImageLabelsState(value);
+        persistToStore(groupTitle, groupSubtitle, groupContent, imageUrl, articles, value);
     };
     return {
         isGrouped,
@@ -213,10 +232,12 @@ export function useBasicQuestionGroup({ partId, groups, questionIndexInPart, ini
         groupContent,
         imageUrl,
         articles,
+        imageLabels,
         setGroupTitle,
         setGroupSubtitle,
         setGroupContent,
         setImageUrl,
         setArticles,
+        setImageLabels,
     };
 }

package/dist/components/questions/_shared/types/fill-in-blank.type.d.ts

@@ -40,6 +40,11 @@ export interface FillInBlankData {
     groupImageUrl?: string;
     groupNumber?: number;
     groups?: FillInBlankGroup[];
+    /** Picture + label bank when groupType === "IMAGE_LABEL" */
+    imageLabels?: Array<{
+        imageUrl: string;
+        label: string;
+    }>;
     blanks?: BlankItem[];
 }
 export interface FillInBlankCreatorProps {
@@ -55,6 +60,10 @@ export interface FillInBlankCreatorProps {
     partId?: string;
     /** Template questionConfig — controls which fields are shown (e.g. "audio") */
     questionConfig?: string[];
+    /** Template group.type (e.g. IMAGE_LABEL) */
+    groupType?: string;
+    /** Template suggestedAnswers — prefill IMAGE_LABEL labels when empty */
+    suggestedAnswers?: string[];
 }
 export interface FillInBlankClientProps {
     questionData: FillInBlankData;

package/dist/components/questions/_shared/types/question-group.type.d.ts

@@ -6,6 +6,7 @@
  *
  * Different question types may use different group shapes:
  *   - BasicGroupData  → ANSWER_THE_QUESTION, CHOOSE_THE_CORRECT_ANSWER, FILL_IN_BLANK
+ *   - IMAGE_LABEL     → FILL_IN_BLANK word bank (image + label items)
  *   - (future)        → MATCH_BY_WRITING_ANSWER, LISTENING_*, etc.
  */
 /** One entry in a part's group configuration array */
@@ -24,6 +25,14 @@ export interface ArticleData {
     /** Hình ảnh – S3 key hoặc URL */
     imageUrl: string;
 }
+/** One item in an IMAGE_LABEL word bank (e.g. GET Primary vocabulary box) */
+export interface ImageLabelData {
+    /** Hình ảnh – S3 key hoặc URL */
+    imageUrl: string;
+    /** Nhãn / từ hiển thị dưới ảnh */
+    label: string;
+}
+export declare function hasImageLabels(items?: ImageLabelData[] | null): boolean;
 /**
  * Shared context fields for a group of ANSWER_THE_QUESTION,
  * CHOOSE_THE_CORRECT_ANSWER, or FILL_IN_BLANK questions.
@@ -41,4 +50,6 @@ export interface BasicGroupData {
     imageUrl?: string;
     /** Mảng bài viết – dùng cho groupType "ARTICLES" (optional) */
     articles?: ArticleData[];
+    /** Mảng ảnh + nhãn – dùng cho groupType "IMAGE_LABEL" (optional) */
+    imageLabels?: ImageLabelData[];
 }

package/dist/components/questions/_shared/types/question-group.type.js

@@ -6,6 +6,9 @@
  *
  * Different question types may use different group shapes:
  *   - BasicGroupData  → ANSWER_THE_QUESTION, CHOOSE_THE_CORRECT_ANSWER, FILL_IN_BLANK
+ *   - IMAGE_LABEL     → FILL_IN_BLANK word bank (image + label items)
  *   - (future)        → MATCH_BY_WRITING_ANSWER, LISTENING_*, etc.
  */
-export {};
+export function hasImageLabels(items) {
+    return Array.isArray(items) && items.some((item) => Boolean(item?.imageUrl?.trim() || item?.label?.trim()));
+}

package/dist/components/questions/_shared/types/spontaneous-qa.type.d.ts

@@ -13,6 +13,13 @@ export interface SpontaneousQAData {
     /** Points per question */
     points?: number;
 }
+export interface SpontaneousQAClientProps {
+    questionData: SpontaneousQAData & {
+        isBackup?: boolean;
+        expectedAnswers?: string[];
+    };
+    isReviewMode?: boolean;
+}
 export interface SpontaneousQACreatorProps {
     initialData?: SpontaneousQAData;
     onSave?: (data: SpontaneousQAData) => void;