@edpire/sdk 0.5.0

package/dist/react.d.mts

@@ -0,0 +1,200 @@
+import React from 'react';
+import { RuntimeAnswer, AssessmentContent, AssessmentAnswers, QuestionRuntimeProps } from '@youssefalmia/edpire-runtime';
+export { RuntimeAnswer } from '@youssefalmia/edpire-runtime';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { RichContent } from '@youssefalmia/edpire-schema/authoring';
+
+/**
+ * EdpireQuestion — public React component for rendering a single question.
+ *
+ * Wraps QuestionRuntime from @youssefalmia/edpire-runtime behind a stable
+ * public API. Consumers never import the internal runtime package directly.
+ *
+ * Key conveniences over using QuestionRuntime directly:
+ * - `feedback` accepts a plain JSON object (from POST /check) and converts
+ *   it to the Map<nodeId, ValidationFeedback> that QuestionRuntime expects.
+ * - `dir` wraps the question in a container with the correct text direction.
+ * - CSS for feedback states is bundled and injected automatically.
+ */
+
+interface EdpireQuestionProps {
+    /**
+     * The question's ContentAST — the `content_ast` field from
+     * GET /api/v1/assessments/{id} → exercises[n].questions[n].
+     */
+    content: unknown;
+    /**
+     * Called on every answer change. Receives the current array of RuntimeAnswers.
+     * Collect these and pass them to POST /check or your submit endpoint.
+     */
+    onAnswersChange?: (answers: RuntimeAnswer[]) => void;
+    /**
+     * Feedback from POST /api/v1/assessments/{id}/check.
+     * Pass the `feedback` field from the response directly — no conversion needed.
+     * The component converts the plain object to the Map expected by QuestionRuntime.
+     *
+     * Set to null/undefined to clear feedback (e.g. when moving to the next question).
+     */
+    feedback?: Record<string, unknown> | null;
+    /**
+     * Pre-fill answers — useful for restoring state when navigating back.
+     */
+    initialAnswers?: RuntimeAnswer[];
+    /**
+     * CSS class added to the question root div.
+     */
+    className?: string;
+    /**
+     * Text direction. Wrap in an rtl container for Arabic content.
+     * Defaults to "ltr".
+     */
+    dir?: "ltr" | "rtl";
+}
+declare const EdpireQuestion: React.NamedExoticComponent<EdpireQuestionProps>;
+
+type SpinnerTheme = "default" | "dots" | "pulse" | "bars";
+interface GradingOverlayProps {
+    visible: boolean;
+    bgColor?: string;
+    accentColor?: string;
+    text?: string;
+    aiText?: string;
+    spinnerTheme?: SpinnerTheme;
+    animationUrl?: string;
+    hasAiNodes?: boolean;
+    contained?: boolean;
+}
+type OverlayConfig = Pick<GradingOverlayProps, "bgColor" | "accentColor" | "text" | "spinnerTheme" | "animationUrl">;
+
+/**
+ * Standalone, dependency-free i18n for the SDK shell.
+ *
+ * Replaces the web app's `useTranslations("learner.taking")` so the shell can
+ * be rendered in any React environment (Vite, CRA, Astro, UMD CDN, mobile
+ * WebView). Locale is passed as a prop — there is no React context to set up.
+ *
+ * Strings mirror `packages/i18n/messages/{en,fr,ar}.json` under `learner.taking.*`.
+ * Keep in sync if those copies are edited.
+ */
+type ShellLocale = "en" | "fr" | "ar";
+
+/**
+ * Public types for the polished Assessment Shell.
+ *
+ * The shell renders the same UI used at edpire.com's hosted player.
+ * Consumers using the EdpireAssessment.mount() API get these types
+ * indirectly via MountOptions; consumers rendering <AssessmentShell>
+ * directly import them from "@edpire/sdk/react".
+ */
+
+/** Branding payload accepted by AssessmentShell. Mirrors what edpire.com sends. */
+interface TakeBranding {
+    /** Org display name — shown as the alt text on the logo. */
+    name: string;
+    /** Logo URL (any https URL). When absent, the Edpire logo is shown. */
+    logoUrl: string | null;
+    branding: {
+        /** CSS color for the primary action buttons (Submit, View Report, etc.). */
+        primaryColor?: string;
+        /** CSS color used as the background of the top bar and per-exercise headers. */
+        accentColor?: string;
+        /** font-family applied to the shell. Pair with `fontUrl` for non-system fonts. */
+        fontFamily?: string;
+        /** A Google Fonts stylesheet URL; the shell injects a <link> tag at mount. */
+        fontUrl?: string;
+        /** When false, the "Powered by Edpire" watermark is hidden. Default true. */
+        showPoweredBy?: boolean;
+    } | null;
+}
+type NodeDetail = {
+    type: "choiceSet";
+    correctChoiceIds: string[];
+} | {
+    type: "matchingSet";
+    pairFeedback: Array<{
+        leftId: string;
+        rightId: string;
+        correct: boolean;
+    }>;
+    correctPairings: Array<{
+        leftId: string;
+        rightId: string;
+    }>;
+};
+interface NodeFeedback {
+    nodeId: string;
+    status: "correct" | "partial" | "incorrect" | "awaiting_review";
+    score: number;
+    maxScore: number;
+    feedback?: string;
+    displayAnswer?: string;
+    detail?: NodeDetail;
+    teacherFeedback?: RichContent[];
+}
+interface QuestionFeedback {
+    questionId: string;
+    nodeResults: NodeFeedback[];
+}
+interface ExerciseFeedbackData {
+    exerciseId: string;
+    questions: QuestionFeedback[];
+}
+interface SubmitResult {
+    submissionId: string;
+    totalScore: number;
+    maxScore: number;
+    percentage: number;
+    passed: boolean;
+    /** If null/undefined, the shell hides the "View Full Report" button. */
+    returnUrl?: string | null;
+    exerciseFeedback: ExerciseFeedbackData[];
+    /** When true, score banners hide the score (still being reviewed). */
+    awaitingManualGrading?: boolean;
+}
+
+interface AssessmentShellProps {
+    assessment: AssessmentContent;
+    meta: {
+        title: string;
+        category: string | null;
+    };
+    /** Locale for shell strings. Default "en". */
+    locale?: ShellLocale;
+    branding?: TakeBranding;
+    /** Time limit in minutes — shows a countdown chip and auto-submits at 0:00. */
+    timeLimitMinutes?: number | null;
+    /** ISO timestamp of attempt start — anchors the countdown server-side. */
+    startedAt?: string;
+    /** Called when the learner submits. Should throw on error. */
+    onSubmit: (answers: AssessmentAnswers) => Promise<SubmitResult>;
+    /** Called when the learner clicks "View Full Report". Omit to hide the button. */
+    onViewReport?: (result: SubmitResult) => void;
+    /** Custom label for the post-submit redirect button (overrides default). */
+    reportLabel?: string;
+    /** Called when the learner clicks the back button (shown only BEFORE submission). */
+    onBack?: () => void;
+    /** Custom label for the back button (default: localized "Back"). */
+    backLabel?: string;
+    /** Show a Reset button in the top bar. */
+    allowReset?: boolean;
+    onReset?: () => void;
+    /** Show a close (✕) button in the top bar. */
+    onClose?: () => void;
+    /** Extra customisation for the grading overlay (branded spinner, etc.). */
+    overlayConfig?: OverlayConfig;
+    /** Scope grading/time-up overlays to this component instead of the viewport. */
+    contained?: boolean;
+    /** Media upload handler — required for file-upload and recording modes in
+     *  OpenResponse questions. */
+    mediaHandler?: QuestionRuntimeProps["mediaHandler"];
+    /**
+     * Logo shown when the org has no `branding.logoUrl`.
+     * Defaults to an inline Edpire SVG so the SDK has zero asset dependencies.
+     * In edpire.com itself, pass "/edpire_logo_blue.png" to preserve the original
+     * Next.js-served asset.
+     */
+    fallbackLogoUrl?: string;
+}
+declare function AssessmentShell({ assessment, meta, locale, branding, timeLimitMinutes, startedAt, onSubmit, onViewReport, reportLabel, onBack, backLabel, allowReset, onReset, overlayConfig, contained, onClose, mediaHandler, fallbackLogoUrl, }: AssessmentShellProps): react_jsx_runtime.JSX.Element;
+
+export { AssessmentShell, type AssessmentShellProps, EdpireQuestion, type EdpireQuestionProps, type ExerciseFeedbackData, type NodeDetail, type NodeFeedback, type OverlayConfig, type QuestionFeedback, type ShellLocale, type SpinnerTheme, type SubmitResult, type TakeBranding };