@tinyweb_dev/oe-exam-sdk 0.2.1 → 0.2.2

package/dist/shared/constants/question-skills.js

@@ -79,6 +79,7 @@ export const QUESTION_TYPE_SKILLS = {
     'FILL_BLANK': SkillEnum.READING,
     'WORD_FILL_STRUCTURED_FORM': SkillEnum.READING,
     'CROSSWORD_PUZZLE': SkillEnum.READING,
+    'FIND_WORDS_IN_MATRIX': SkillEnum.READING,
     // ========================================
     // WRITING SKILLS (Viết)
     // ========================================
@@ -206,6 +207,7 @@ export const QUESTION_TYPE_LABELS = {
     'MATCH_BY_WRITING_ANSWER': 'Ghép đáp án bằng cách viết',
     'WORD_FILL_STRUCTURED_FORM': 'Điền từ vào biểu mẫu có cấu trúc',
     'CROSSWORD_PUZZLE': 'Giải ô chữ (Crossword)',
+    'FIND_WORDS_IN_MATRIX': 'Tìm từ trong ma trận (Word Search)',
     // ========================================
     // WRITING SKILLS (Viết)
     // ========================================

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

@@ -447,6 +447,7 @@ const handlers = {
     SPEAKING_CUE_CARD: reverseSimpleAnswer,
     GN_SPEAKING_INTERVIEW: reverseGroupPayload,
     CROSSWORD_PUZZLE: reverseCrosswordPuzzle,
+    FIND_WORDS_IN_MATRIX: reverseFindWordsInMatrix,
 };
 function reverseCrosswordPuzzle(apiQuestion) {
     const apiContent = (apiQuestion.content || {});
@@ -501,6 +502,68 @@ function reverseCrosswordPuzzle(apiQuestion) {
         },
     };
 }
+function reverseFindWordsInMatrix(apiQuestion) {
+    const apiContent = (apiQuestion.content || {});
+    const apiAnswer = (apiQuestion.correctAnswer || apiQuestion.correct_answer || apiQuestion.answer || {});
+    const type = apiContent.type || (Array.isArray(apiContent.categories) && apiContent.categories.length > 0 ? 'CATEGORIZE' : 'WORD_BANK');
+    const rows = apiContent.gridSize?.rows || (Array.isArray(apiContent.grid) ? apiContent.grid.length : 14);
+    const cols = apiContent.gridSize?.cols || (Array.isArray(apiContent.grid?.[0]) ? apiContent.grid[0].length : 14);
+    const title = apiContent.title || '';
+    const grid = Array.isArray(apiContent.grid) ? apiContent.grid : [];
+    const categories = Array.isArray(apiContent.categories) ? apiContent.categories : [];
+    const wordBank = Array.isArray(apiContent.wordBank) ? apiContent.wordBank : [];
+    const correctWords = Array.isArray(apiAnswer.words) ? apiAnswer.words : [];
+    const correctMap = new Map();
+    for (const cw of correctWords) {
+        if (cw.wordId) {
+            correctMap.set(cw.wordId, cw);
+        }
+    }
+    const words = wordBank.map((wb) => {
+        const isEx = Boolean(wb.isExample);
+        const correctInfo = correctMap.get(wb.id);
+        let path = correctInfo?.path;
+        let categoryId = wb.categoryId || correctInfo?.categoryId;
+        if (isEx && apiContent.exampleSelection?.wordId === wb.id) {
+            path = apiContent.exampleSelection.path;
+            if (apiContent.exampleSelection.categoryId) {
+                categoryId = apiContent.exampleSelection.categoryId;
+            }
+        }
+        return {
+            id: wb.id || `w_${Math.random().toString(36).substring(2, 9)}`,
+            word: wb.word || '',
+            isExample: isEx,
+            ...(categoryId ? { categoryId } : {}),
+            path: path || [],
+        };
+    });
+    return {
+        content: {
+            type,
+            title,
+            rows,
+            cols,
+            gridSize: { rows, cols },
+            grid,
+            categories,
+            wordBank,
+            words,
+            ...(apiContent.exampleSelection ? { exampleSelection: apiContent.exampleSelection } : {}),
+        },
+        answer: {
+            type,
+            title,
+            rows,
+            cols,
+            grid,
+            categories,
+            words,
+            caseSensitive: Boolean(apiAnswer.caseSensitive),
+            explanation: apiQuestion.explanation || '',
+        },
+    };
+}
 export function transformApiQuestionToFrontend(apiQuestion) {
     const questionType = String(apiQuestion.questionType ?? apiQuestion.question_type ?? apiQuestion.type ?? '');
     const handlerResult = (handlers[questionType] ?? defaultReverse)(apiQuestion);

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

@@ -42,6 +42,7 @@ import { transformSpeakingCueCard } from '../../../components/questions/types/sp
 import { transformGNSpeakingInterview } from '../../../components/questions/types/gn-speaking-interview/transform';
 import { transformWordFillStructuredForm } from '../../../components/questions/types/word-fill-structured-form/transform';
 import { transformCrosswordPuzzle } from '../../../components/questions/types/crossword-puzzle/transform';
+import { transformFindWordsInMatrix } from '../../../components/questions/types/find-words-in-matrix/transform';
 // ─── Handler map ────────────────────────────────────────────────────────────
 const questionTransformHandlers = {
     // Look picture
@@ -90,6 +91,7 @@ const questionTransformHandlers = {
     GN_SPEAKING_INTERVIEW: transformGNSpeakingInterview,
     WORD_FILL_STRUCTURED_FORM: transformWordFillStructuredForm,
     CROSSWORD_PUZZLE: transformCrosswordPuzzle,
+    FIND_WORDS_IN_MATRIX: transformFindWordsInMatrix,
 };
 /**
  * Transform frontend question format to API format.

package/dist/shared/types/common.types.d.ts

@@ -29,7 +29,7 @@ export declare enum StudentSelectionType {
 }
 export type ResultStatus = 'PENDING' | 'PARTIAL_GRADED' | 'GRADED';
 export type StudentStatus = 'NOT_STARTED' | 'IN_PROGRESS' | 'SUBMITTED';
-export type QuestionType = 'FILL_IN_BLANK' | 'TRUE_FALSE' | 'MATCHING' | 'ORDERING' | 'LISTENING' | 'COLORING' | 'ESSAY' | 'LISTEN_AND_FILL_IN_THE_BLANK_WITH_IMAGE' | 'LISTEN_AND_TICK_ANSWER' | 'LISTEN_AND_FILL_NAME_NUMBER' | 'LISTENING_FILL_BLANK' | 'LISTENING_COLOR' | 'TICK_TRUE_OR_FALSE' | 'TICK_YES_OR_NO' | 'READING_TICK_CROSS' | 'ARRANGE_LETTERS_INTO_WORDS' | 'READ_PASSAGE_AND_COMPLETE_STORY' | 'CLOZE_TEST_WITH_TICK_BOX' | 'READ_AND_CHOOSE_APPROPRIATE_WORD' | 'WRITE_SHORT_PARAGRAPH' | 'LABEL_THE_PICTURE' | 'READING_LETTER_ARRANGE' | 'READING_PASSAGE_FILL' | 'FILL_BLANK' | 'FILL_MISSING_WORDS_IN_GRID' | 'LOOK_PICTURE_CHOOSE_CORRECT_ANSWER' | 'LOOK_PICTURE_FILL_BLANK_CHOOSE_ANSWER' | 'LOOK_PICTURE_FILL_WORD_HINT' | 'LABEL_THE_PICTURE' | 'READ_AND_COLOR_OBJECTS' | 'IMAGE_OBJECT_MATCHING' | 'READ_PASSAGE_AND_ANSWER_QUESTIONS' | 'CHOOSE_THE_CORRECT_ANSWER' | 'CHOOSE_THE_CORRECT_ANSWER_GROUP' | 'TRUE_FALSE_GROUP' | 'CROSS_OUT_WORD_GROUP' | 'SPONTANEOUS_QA_GROUP' | 'WORD_ORDER_AND_MATCH_GROUP' | 'WRITE_A_SHORT_LETTER' | 'WRITE_CORRECT_VERB_FORM' | 'CHOOSE_CORRECT_ADJECTIVE' | 'ANSWER_THE_QUESTION' | 'ANSWER_THE_QUESTION_GROUP' | 'WORD_ORDERING' | 'WORD_FILL_PARAGRAPH' | 'MATCH_BY_WRITING_ANSWER' | 'WRITE_SENTENCES' | 'LISTEN_AND_CHOOSE_FROM_ANSWER_GROUP' | 'LISTEN_AND_CHOOSE_OBJECTS_IN_SCENE' | 'LISTEN_AND_DRAG_OBJECTS_INTO_SCENE' | 'LISTEN_AND_SPEAK_ANSWER' | 'LISTEN_AND_SPEAK_IMAGE_GROUP' | 'LISTEN_AND_SPEAK_QUESTION_LIST' | 'LISTEN_AND_SPEAK_COMPARE_IMAGES' | 'LISTEN_AND_SPEAK_WITH_STORY_IMAGES' | 'LISTEN_AND_SPEAK_ODD_ONE_OUT' | 'LISTEN_AND_SPEAK_INFO_EXCHANGE' | 'READ_DISPLAYED_CONTENT' | 'SPEAKING_DESCRIBE_IMAGE' | 'SPONTANEOUS_QA' | 'SPEAKING_CONVERSATION' | 'GN_SPEAKING_INTERVIEW' | 'SPEAKING_CUE_CARD' | 'WORD_FILL_STRUCTURED_FORM' | 'CROSSWORD_PUZZLE';
+export type QuestionType = 'FILL_IN_BLANK' | 'TRUE_FALSE' | 'MATCHING' | 'ORDERING' | 'LISTENING' | 'COLORING' | 'ESSAY' | 'LISTEN_AND_FILL_IN_THE_BLANK_WITH_IMAGE' | 'LISTEN_AND_TICK_ANSWER' | 'LISTEN_AND_FILL_NAME_NUMBER' | 'LISTENING_FILL_BLANK' | 'LISTENING_COLOR' | 'TICK_TRUE_OR_FALSE' | 'TICK_YES_OR_NO' | 'READING_TICK_CROSS' | 'ARRANGE_LETTERS_INTO_WORDS' | 'READ_PASSAGE_AND_COMPLETE_STORY' | 'CLOZE_TEST_WITH_TICK_BOX' | 'READ_AND_CHOOSE_APPROPRIATE_WORD' | 'WRITE_SHORT_PARAGRAPH' | 'LABEL_THE_PICTURE' | 'READING_LETTER_ARRANGE' | 'READING_PASSAGE_FILL' | 'FILL_BLANK' | 'FILL_MISSING_WORDS_IN_GRID' | 'LOOK_PICTURE_CHOOSE_CORRECT_ANSWER' | 'LOOK_PICTURE_FILL_BLANK_CHOOSE_ANSWER' | 'LOOK_PICTURE_FILL_WORD_HINT' | 'LABEL_THE_PICTURE' | 'READ_AND_COLOR_OBJECTS' | 'IMAGE_OBJECT_MATCHING' | 'READ_PASSAGE_AND_ANSWER_QUESTIONS' | 'CHOOSE_THE_CORRECT_ANSWER' | 'CHOOSE_THE_CORRECT_ANSWER_GROUP' | 'TRUE_FALSE_GROUP' | 'CROSS_OUT_WORD_GROUP' | 'SPONTANEOUS_QA_GROUP' | 'WORD_ORDER_AND_MATCH_GROUP' | 'WRITE_A_SHORT_LETTER' | 'WRITE_CORRECT_VERB_FORM' | 'CHOOSE_CORRECT_ADJECTIVE' | 'ANSWER_THE_QUESTION' | 'ANSWER_THE_QUESTION_GROUP' | 'WORD_ORDERING' | 'WORD_FILL_PARAGRAPH' | 'MATCH_BY_WRITING_ANSWER' | 'WRITE_SENTENCES' | 'LISTEN_AND_CHOOSE_FROM_ANSWER_GROUP' | 'LISTEN_AND_CHOOSE_OBJECTS_IN_SCENE' | 'LISTEN_AND_DRAG_OBJECTS_INTO_SCENE' | 'LISTEN_AND_SPEAK_ANSWER' | 'LISTEN_AND_SPEAK_IMAGE_GROUP' | 'LISTEN_AND_SPEAK_QUESTION_LIST' | 'LISTEN_AND_SPEAK_COMPARE_IMAGES' | 'LISTEN_AND_SPEAK_WITH_STORY_IMAGES' | 'LISTEN_AND_SPEAK_ODD_ONE_OUT' | 'LISTEN_AND_SPEAK_INFO_EXCHANGE' | 'READ_DISPLAYED_CONTENT' | 'SPEAKING_DESCRIBE_IMAGE' | 'SPONTANEOUS_QA' | 'SPEAKING_CONVERSATION' | 'GN_SPEAKING_INTERVIEW' | 'SPEAKING_CUE_CARD' | 'WORD_FILL_STRUCTURED_FORM' | 'CROSSWORD_PUZZLE' | 'FIND_WORDS_IN_MATRIX';
 export type Level = 'Pre-A1' | 'A1' | 'A2' | 'B1' | 'B2' | 'C1' | 'C2';
 export type Difficulty = 'EASY' | 'MEDIUM' | 'HARD';
 export type Skill = 'LISTENING' | 'READING' | 'WRITING' | 'SPEAKING';

package/dist/shared/types/questions/find-words-in-matrix.d.ts

@@ -0,0 +1,71 @@
+/**
+ * FIND_WORDS_IN_MATRIX Question Type Interfaces (SDK)
+ *
+ * Supported types:
+ * - 'WORD_BANK': Standard word search with given word bank (default).
+ * - 'CATEGORIZE': Word search where words are categorized under headings (e.g. Plants vs Animals).
+ */
+import { QuestionBankSettings } from './choose-the-correct-answer';
+export type FindWordsInMatrixType = 'WORD_BANK' | 'CATEGORIZE';
+export interface MatrixCellCoord {
+    row: number;
+    col: number;
+}
+export interface CategoryHeadingItem {
+    id: string;
+    name: string;
+    color?: string;
+}
+export interface WordBankItem {
+    id: string;
+    word: string;
+    isExample?: boolean;
+    categoryId?: string;
+}
+export interface ExampleSelection {
+    wordId: string;
+    categoryId?: string;
+    path: MatrixCellCoord[];
+}
+export interface FindWordsInMatrixContent {
+    type?: FindWordsInMatrixType;
+    title?: string;
+    gridSize: {
+        rows: number;
+        cols: number;
+    };
+    grid: string[][];
+    categories?: CategoryHeadingItem[];
+    wordBank: WordBankItem[];
+    exampleSelection?: ExampleSelection;
+}
+export interface CorrectWordItem {
+    wordId: string;
+    word?: string;
+    categoryId?: string;
+    path: MatrixCellCoord[];
+}
+export interface FindWordsInMatrixCorrectAnswer {
+    words: CorrectWordItem[];
+    caseSensitive?: boolean;
+}
+export interface StudentWordSelectionItem {
+    wordId?: string;
+    word?: string;
+    categoryId?: string;
+    path: MatrixCellCoord[];
+}
+export interface FindWordsInMatrixAPIPayload {
+    id?: string;
+    questionType: 'FIND_WORDS_IN_MATRIX';
+    content: FindWordsInMatrixContent;
+    correctAnswer: FindWordsInMatrixCorrectAnswer;
+    points: number;
+    explanation?: string;
+    questionNumber: number;
+    partId?: string;
+    partNo?: number;
+    addToQuestionBank?: boolean;
+    questionBank?: QuestionBankSettings;
+}
+export type FindWordsInMatrixLocalStorage = Omit<FindWordsInMatrixAPIPayload, 'addToQuestionBank' | 'questionBank'>;

package/dist/shared/types/questions/find-words-in-matrix.js

@@ -0,0 +1,8 @@
+/**
+ * FIND_WORDS_IN_MATRIX Question Type Interfaces (SDK)
+ *
+ * Supported types:
+ * - 'WORD_BANK': Standard word search with given word bank (default).
+ * - 'CATEGORIZE': Word search where words are categorized under headings (e.g. Plants vs Animals).
+ */
+export {};

package/dist/shared/types/questions/index.d.ts

@@ -31,3 +31,4 @@ export * from './speaking-describe-image';
 export * from './spontaneous-qa';
 export * from './word-order-and-match-group';
 export * from './crossword-puzzle';
+export * from './find-words-in-matrix';

package/dist/shared/types/questions/index.js

@@ -48,3 +48,5 @@ export * from './spontaneous-qa';
 export * from './word-order-and-match-group';
 // CROSSWORD_PUZZLE
 export * from './crossword-puzzle';
+// FIND_WORDS_IN_MATRIX
+export * from './find-words-in-matrix';

package/package.json

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