@tinyweb_dev/oe-exam-sdk 0.1.2 → 0.1.4

package/dist/components/exams/take/types/speaking.types.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Speaking exam types — Cambridge Movers/Flyers
+ *
+ * Covers all 4 speaking question types rendered in the student exam-taking view.
+ * These match the `content` and `questionGroup.payload` shapes from the API.
+ */
+export interface CompareImagesContent {
+    audioUrl: string;
+    isBackup?: boolean;
+}
+export interface CompareImagesGroupPayload {
+    candidateImageUrl: string;
+    examinerImageUrl: string;
+}
+export interface StoryImagesContent {
+    audioUrl: string;
+    images: string[];
+    isBackup?: boolean;
+}
+export interface OddOneOutContent {
+    audioUrl: string;
+    activeImageId?: string;
+    images?: string[];
+    isBackup?: boolean;
+}
+export interface OddOneOutGroupPayload {
+    images: Array<{
+        id: string;
+        url: string;
+        label: string;
+    }>;
+}
+export interface QuestionListContent {
+    audioUrl: string;
+    activeQuestionId: string;
+    isBackup?: boolean;
+}
+export interface QuestionListGroupPayload {
+    content?: Array<{
+        id: string;
+        text: string;
+    }>;
+    questions?: Array<{
+        id: string;
+        text: string;
+    }>;
+}
+export interface InfoExchangeContent {
+    audioUrl: string;
+    isBackup?: boolean;
+}
+export interface InfoExchangeGroupPayload {
+    title: string;
+    imageUrl: string;
+    candidateFields: Array<{
+        key: string;
+        answer: string;
+    }>;
+    examinerFields: Array<{
+        key: string;
+        answer: string;
+    }>;
+}
+export interface ReadDisplayedContentContent {
+    /** The reference text passage the student must read aloud */
+    referenceText: string;
+    /** Optional: audio URL of a model/native pronunciation for reference */
+    modelAudioUrl?: string;
+    /** Optional: difficulty tag for the passage */
+    difficultyTag?: 'BASIC_PHONICS' | 'DAILY_ROUTINE' | 'DESCRIPTIVE_EMOTIONAL';
+    /** Backup flag - consistent with other speaking types */
+    isBackup?: boolean;
+}
+export interface SpontaneousQAContent {
+    /** How the admin created this question: uploaded audio or entered text */
+    inputType: 'AUDIO' | 'TEXT';
+    /** Audio URL — always present at client render time */
+    audioUrl?: string;
+    /** Question text — only visible in admin/review mode, not shown to student */
+    questionText?: string;
+    /** Backup flag — consistent with other speaking types */
+    isBackup?: boolean;
+}
+export interface GNSpeakingInterviewContent {
+    /** Examiner's question text */
+    questionText: string;
+    /** Audio URL for examiner's question (TTS or uploaded) */
+    audioUrl?: string;
+    /** How admin created the question */
+    inputType: 'AUDIO' | 'TEXT';
+    /** Which candidate this question is addressed to */
+    targetCandidate: 'VIRTUAL' | 'REAL';
+    /** Booklet image URL — collage for Part 2 Discussion with Pictures */
+    imageUrl?: string;
+    /** Virtual student's pre-recorded answer (filled by admin) */
+    virtualAnswer?: {
+        /** Text of the virtual student's answer */
+        answerText: string;
+        /** Audio URL — admin uploads or auto-generates via TTS */
+        audioUrl?: string;
+    };
+    /** Whether this is an Extended Response question */
+    isExtendedResponse?: boolean;
+    /** Backup flag */
+    isBackup?: boolean;
+}
+export interface GNSpeakingInterviewGroupPayload {
+    /** Which candidate role is virtual (pre-recorded) */
+    virtualCandidate: 'A' | 'B';
+    /** Virtual student display name */
+    virtualStudentName?: string;
+    /** Virtual student avatar image URL */
+    virtualStudentAvatar?: string;
+}
+/** Answer stored in examTakingStore for speaking questions */
+export interface SpeakingAnswer {
+    audioUrl: string;
+}
+/** Recording state managed by useSpeakingRecorder hook */
+export interface RecordingState {
+    status: 'idle' | 'recording' | 'recorded' | 'uploading' | 'uploaded' | 'error';
+    remainingSeconds: number;
+    isWarning: boolean;
+    durationSeconds: number;
+    audioBlob: Blob | null;
+    audioUrl: string | null;
+    uploadedKey: string | null;
+    error: string | null;
+    isAttemptExpired: boolean;
+}
+/** Response from POST /api/v1/student/attempts/:id/audio-answer */
+export interface UploadAudioAnswerResponse {
+    questionId: string;
+    audioKey: string;
+    answeredAt: string;
+}
+export type SpeakingConversationResponder = 'PARTNER' | 'STUDENT';
+export interface SpeakingConversationContent {
+    interlocutorAudioUrl?: string;
+    partnerAudioUrl?: string;
+    responder: SpeakingConversationResponder;
+    questionText?: string;
+    isBackup?: boolean;
+}
+export interface SpeakingConversationGroupPayload {
+    images?: Array<{
+        id: string;
+        url: string;
+        label: string;
+    }>;
+    partnerName?: string;
+    partnerAvatarUrl?: string;
+}

package/dist/components/exams/take/types/speaking.types.js

@@ -0,0 +1 @@
+export{};

package/dist/components/exams/take/types.d.ts

@@ -1 +1,286 @@
-export type { ExamTakingAnswerValue, ExamTakingAttempt, ExamTakingQuestion, ExamTakingQuestionsResult, ExamTakingSdkApi, ExamTakingTemplatePart, SaveExamTakingAnswersInput } from '../../../api/exam-taking';
+/**
+ * Types for Movers Exam UI
+ */
+import type { ReactNode } from 'react';
+export interface FillBlankQuestion {
+    id: string;
+    questionNumber: number;
+    textBefore: string;
+    textAfter: string;
+    verbHint?: string;
+    correctAnswer?: string;
+    imageUrl?: string;
+    hints?: string[];
+    isExample?: boolean;
+}
+export interface MoversListenAndWriteRendererProps {
+    partNumber: number;
+    partName?: string;
+    questionCount: number;
+    instruction: string;
+    imageUrl?: string;
+    audioUrl?: string;
+    title: string;
+    exampleText?: string;
+    exampleHighlight?: string;
+    questions: FillBlankQuestion[];
+    answers: Record<string, string>;
+    onAnswerChange: (questionId: string, value: string) => void;
+    isReviewMode?: boolean;
+    showHints?: boolean;
+}
+export interface MoversExamLayoutProps {
+    children: ReactNode;
+    headerProps: {
+        remainingSeconds: number;
+        totalQuestions: number;
+        answeredCount: number;
+        progress: number;
+    };
+    onPrevious: () => void;
+    onNext: () => void;
+    isFirstQuestion: boolean;
+    isLastQuestion: boolean;
+}
+export interface MoversQuestionCardProps {
+    children: ReactNode;
+    className?: string;
+}
+export interface MoversPartBannerProps {
+    partNumber: number;
+    questionCount: number;
+    partName?: string;
+}
+export interface MoversInstructionBannerProps {
+    instruction: string;
+}
+export interface MoversAudioPlayerProps {
+    audioUrl: string;
+}
+export interface MoversExampleTextProps {
+    text: string;
+    highlight?: string;
+}
+export interface WritingQuestion {
+    id: string;
+    partNumber: number;
+    prompt: string;
+    requirements?: string[];
+    minWords?: number;
+    maxWords?: number;
+}
+export interface MoversWritingRendererProps {
+    partNumber: number;
+    prompt: string;
+    requirements?: string[];
+    minWords?: number;
+    maxWords?: number;
+    answer: string;
+    onAnswerChange: (value: string) => void;
+    isReviewMode?: boolean;
+}
+/** Hint item - có thể là color-only, text-only, hoặc cả hai */
+export interface ColoringHintItem {
+    id: string;
+    color?: string;
+    label?: string;
+}
+/** Region trên image để drop hint */
+export interface ColoringRegion {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    correctHintId: string;
+}
+/** Props cho MoversColoringRenderer */
+export interface MoversColoringRendererProps {
+    partNumber: number;
+    partName?: string;
+    questionCount: number;
+    instruction: string;
+    instructions?: string[];
+    hasExample?: boolean;
+    imageUrl: string;
+    audioUrl?: string;
+    hintItems: ColoringHintItem[];
+    regions: ColoringRegion[];
+    assignments: Record<string, string>;
+    onAssignmentChange: (regionId: string, hintItemId: string | null) => void;
+    isReviewMode?: boolean;
+}
+export interface ChooseBestAnswerOption {
+    id: string;
+    label: string;
+    text: string;
+}
+export interface ChooseBestAnswerQuestion {
+    id: string;
+    questionNumber: number;
+    questionText: string;
+    options: ChooseBestAnswerOption[];
+    correctOptionId?: string;
+    correctOptionIds?: string[];
+    imageUrl?: string;
+    optionType?: 'text' | 'image';
+    multipleAnswers?: boolean;
+    explanation?: string;
+}
+export interface ChooseBestAnswerExample {
+    questionNumber: number;
+    questionText: string;
+    options: ChooseBestAnswerOption[];
+    correctOptionId: string;
+    optionType?: 'text' | 'image';
+    imageUrl?: string;
+}
+export interface MoversChooseBestAnswerRendererProps {
+    partNumber: number;
+    partName?: string;
+    questionCount: number;
+    instruction: string;
+    imageUrl?: string;
+    groupTitle?: string;
+    groupContent?: string;
+    audioUrl?: string;
+    example?: ChooseBestAnswerExample;
+    questions: ChooseBestAnswerQuestion[];
+    answers: Record<string, string | string[]>;
+    onAnswerChange: (questionId: string, optionId: string | string[]) => void;
+    isReviewMode?: boolean;
+    articles?: ArticleItem[];
+}
+/** Article data for ARTICLES group type (e.g., KFS Reading Part 2) */
+export interface ArticleItem {
+    name: string;
+    content: string;
+    imageUrl?: string;
+}
+export interface PictureChooseOption {
+    id: string;
+    label: string;
+    text: string;
+}
+export interface PictureChooseSubQuestion {
+    id: string;
+    questionNumber: number;
+    imageUrl: string;
+    questionText?: string;
+    options: PictureChooseOption[];
+    correctOptionId?: string;
+}
+export interface MoversPictureChooseRendererProps {
+    partNumber: number;
+    partName?: string;
+    questionCount: number;
+    instruction: string;
+    subQuestions: PictureChooseSubQuestion[];
+    answers: Record<string, string>;
+    onAnswerChange: (subQuestionId: string, optionId: string) => void;
+    isReviewMode?: boolean;
+}
+export interface PictureFillBlankOption {
+    id: string;
+    label: string;
+    text: string;
+}
+export interface PictureFillBlankSubQuestion {
+    id: string;
+    questionNumber: number;
+    imageUrl: string;
+    question: string;
+    options: PictureFillBlankOption[];
+    correctOptionId?: string;
+}
+export interface MoversPictureFillBlankChooseRendererProps {
+    partNumber: number;
+    partName?: string;
+    questionCount: number;
+    instruction: string;
+    subQuestions: PictureFillBlankSubQuestion[];
+    answers: Record<string, string>;
+    onAnswerChange: (subQuestionId: string, optionId: string) => void;
+    isReviewMode?: boolean;
+}
+export interface ReadingPassageOption {
+    id: string;
+    label: string;
+    text: string;
+}
+export interface ReadingPassageQuestion {
+    id: string;
+    questionNumber: number;
+    questionText: string;
+    options: ReadingPassageOption[];
+    correctOptionId?: string;
+}
+export interface MoversReadingPassageRendererProps {
+    partNumber: number;
+    partName?: string;
+    questionCount: number;
+    instruction: string;
+    passageTitle?: string;
+    passage: string;
+    passageImageUrl?: string;
+    questions: ReadingPassageQuestion[];
+    answers: Record<string, string>;
+    onAnswerChange: (questionId: string, optionId: string) => void;
+    isReviewMode?: boolean;
+    correctOptionIdMap?: Record<string, string>;
+}
+export interface LabelThePictureLabel {
+    id: string;
+    number: number;
+    correctAnswer?: string;
+    isPreFilled?: boolean;
+}
+export interface MoversLabelThePictureRendererProps {
+    partNumber: number;
+    partName?: string;
+    questionCount: number;
+    instruction: string;
+    imageUrl: string;
+    wordBank: string[];
+    labels: LabelThePictureLabel[];
+    answers: Record<string, string>;
+    onAnswerChange: (labelId: string, value: string) => void;
+    isReviewMode?: boolean;
+}
+export interface FillWordHintSubQuestion {
+    id: string;
+    questionNumber: number;
+    imageUrl: string;
+    word: string;
+    correctAnswer?: string;
+    blankIndex?: number;
+}
+export interface MoversFillWordHintRendererProps {
+    partNumber: number;
+    partName?: string;
+    questionCount: number;
+    instruction: string;
+    hintLetters: string[];
+    subQuestions: FillWordHintSubQuestion[];
+    answers: Record<string, string>;
+    onAnswerChange: (subQuestionId: string, value: string) => void;
+    isReviewMode?: boolean;
+}
+export interface GridCellAnswer {
+    correctAnswer: string;
+}
+export interface MoversGridFillRendererProps {
+    partNumber: number;
+    partName?: string;
+    questionCount: number;
+    instruction: string;
+    grid: (string | null)[][];
+    rows: number;
+    columns: number;
+    cellAnswers: Record<string, GridCellAnswer>;
+    answers: Record<string, string>;
+    onAnswerChange: (cellKey: string, value: string) => void;
+    isReviewMode?: boolean;
+    caseSensitive?: boolean;
+    disabledCells?: string[];
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Answer Transformers - Transform frontend answers to API format
+ *
+ * Frontend stores answers with synthetic IDs for UI convenience.
+ * This module transforms them to the format backend expects.
+ *
+ * Backend grading service expects:
+ * - Single choice: { answer: optionIndex } or { optionId: "uuid" }
+ * - Fill blank: { answer: "text" } or { answers: ["text1", "text2"] }
+ * - Matching: { pairs: [{ left: "id1", right: "id2" }] }
+ */
+import type { SaveAnswerRequest } from '../../../../shared/types/student.types';
+import type { QuestionPart } from './question-transformers';
+/**
+ * Transform frontend answers to API format
+ *
+ * @param answers - Record of questionId -> answer from store
+ * @param parts - Question parts for context
+ * @returns Array of SaveAnswerRequest ready for API
+ */
+export declare function transformAnswersForSubmission(answers: Record<string, any>, parts: QuestionPart[]): SaveAnswerRequest[];
+/**
+ * Get all valid question IDs from parts
+ * Used to filter out invalid IDs before submission
+ */
+export declare function getValidQuestionIds(parts: QuestionPart[]): Set<string>;

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

@@ -0,0 +1 @@
+function n(n){const t=n.match(/-opt-(\d+)$/);return t?parseInt(t[1],10):0}function t(n){return"string"==typeof n&&n.includes("-opt-")}function e(n){return Array.isArray(n)&&n.every(n=>t(n))}function s(n){return"object"==typeof n&&null!==n&&!Array.isArray(n)&&t(n.optionId)}function o(n){return n.startsWith("sq-")||n.includes("-sq-")||n.includes("-blank-")}function r(n){return/^\d+-\d+$/.test(n)}function i(n){return n.startsWith("label-")}function u(n){return n.startsWith("region-")}function f(n,t){for(const n of t)if("READ_PASSAGE_AND_ANSWER_QUESTIONS"===n.questionType&&n.questions.length>0)return{parentId:n.questions[0].id,questionType:n.questionType};return null}function a(n){for(const t of n)if("FILL_MISSING_WORDS_IN_GRID"===t.questionType&&t.questions.length>0)return{parentId:t.questions[0].id,questionType:t.questionType};return null}function c(n){for(const t of n)if("LABEL_THE_PICTURE"===t.questionType&&t.questions.length>0)return{parentId:t.questions[0].id,questionType:t.questionType};return null}function p(n,t){for(const e of t)if(("READ_AND_COLOR_OBJECTS"===e.questionType||"IMAGE_OBJECT_MATCHING"===e.questionType)&&e.questions.length>0){const t=e.questions[0],s=t.content;if((s?.regions||s?.regionNodes||[]).some(t=>t.id===n))return{parentId:t.id,questionType:e.questionType}}return null}function d(n,t){for(const e of t)if("LOOK_PICTURE_FILL_WORD_HINT"===e.questionType)for(const t of e.questions){if(n.startsWith(`${t.id}-blank-`))return{parentId:t.id,questionType:e.questionType};const s=t.content;if(s?.subQuestions?.some(t=>t.id===n))return{parentId:t.id,questionType:e.questionType}}return null}function I(n,t){for(const e of t)for(const t of e.questions)if(t.id===n)return e.questionType;return null}function q(n,t){return"number"==typeof n||"string"==typeof n?{answer:n}:Array.isArray(n)?"WORD_FILL_PARAGRAPH"===t?{answers:n}:{answer:n}:"object"==typeof n&&null!==n?n:{answer:n}}export function transformAnswersForSubmission(l,y){const T=[],_=new Map,h=new Map,w=new Map,A=new Map,g=new Set;for(const n of y)for(const t of n.questions)"SPEAKING"===t.question_skill_type&&g.add(t.id);for(const[S,b]of Object.entries(l)){if(null==b||""===b)continue;if(g.has(S)&&"string"==typeof b)continue;if(r(S)){const n=a(y);n&&(h.has(n.parentId)||h.set(n.parentId,{}),h.get(n.parentId)[S]=String(b));continue}if(i(S)){const n=c(y);n&&(w.has(n.parentId)||w.set(n.parentId,{}),w.get(n.parentId)[S]=String(b));continue}if(u(S)){const n=p(S,y);n&&(A.has(n.parentId)||A.set(n.parentId,{}),A.get(n.parentId)[S]=String(b));continue}if(o(S)){let e=f(0,y);if(e||(e=d(S,y)),e){_.has(e.parentId)||_.set(e.parentId,{});const s=t(b)?n(b):b;_.get(e.parentId)[S]=s}continue}const l=I(S,y);let E;E=t(b)?q(n(b),l):e(b)?q(b.map(t=>n(t)),l):s(b)?q(n(b.optionId),l):q(b,l),T.push({questionId:S,answer:E})}for(const[n,t]of _){if(Object.keys(t).some(n=>n.includes("-blank-"))){const e=Object.entries(t).sort(([n],[t])=>{const e=n.match(/-blank-(\d+)$/),s=t.match(/-blank-(\d+)$/);return(e?parseInt(e[1],10):0)-(s?parseInt(s[1],10):0)}).map(([,n])=>n).join(", ");T.push({questionId:n,answer:{answer:e}})}else T.push({questionId:n,answer:{subAnswers:t}})}for(const[n,t]of h)T.push({questionId:n,answer:{answers:t}});for(const[n,t]of w)T.push({questionId:n,answer:{answers:t}});for(const[n,t]of A)T.push({questionId:n,answer:{answers:t}});return T}export function getValidQuestionIds(n){const t=new Set;for(const e of n)for(const n of e.questions)t.add(n.id);return t}

package/dist/components/exams/take/utils/coloring-assignments.d.ts

@@ -0,0 +1,5 @@
+export interface ColoringHintItemLike {
+    id: string;
+    color?: string | null;
+}
+export declare function normalizeColoringAssignments(rawAssignments: unknown, hintItems: ColoringHintItemLike[]): Record<string, string>;

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

@@ -0,0 +1 @@
+function t(t){return"object"==typeof t&&null!==t}export function normalizeColoringAssignments(n,r){if(!t(n))return{};const o={};return Object.entries(n).forEach(([n,i])=>{const e=function(n){if("string"==typeof n)return n;if(!t(n))return null;const r=["hintItemId","id","value","color"];for(const t of r){const r=n[t];if("string"==typeof r&&r.trim())return r}return null}(i);if(e){if(e.startsWith("#")){const t=r.find(t=>t.color===e);return void(t&&(o[n]=t.id))}o[n]=e}}),o}