@edpire/sdk 0.6.12 → 0.8.0

package/dist/react.d.mts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { RuntimeAnswer, QuestionRuntimeProps, AssessmentContent, AssessmentAnswers } from '@youssefalmia/edpire-runtime';
+import { RuntimeAnswer, AssessmentAnswers, QuestionRuntimeProps, AssessmentContent } 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';
@@ -40,6 +40,11 @@ interface EdpireQuestionProps {
      * Pre-fill answers — useful for restoring state when navigating back.
      */
     initialAnswers?: RuntimeAnswer[];
+    /**
+     * Lock the question: answers show but cannot be changed. For reviewing a
+     * finished attempt, with `initialAnswers` and `feedback` from `flattenReview()`.
+     */
+    readOnly?: boolean;
     /**
      * CSS class added to the question root div.
      */
@@ -80,6 +85,28 @@ interface TakeBranding {
         showPoweredBy?: boolean;
     } | null;
 }
+/**
+ * Geometry of the question column. Branding covers colour and type; this covers
+ * the one thing branding could not reach.
+ */
+interface ShellLayout {
+    /**
+     * Max width of the question column. Any CSS length, or `"none"` to fill the
+     * container. Default `"48rem"` (768px).
+     *
+     * The default is a reading measure, not an arbitrary cap: at the runtime's
+     * base size it yields roughly 70–90 characters per line, already the top of
+     * the comfortable range. Past about `"60rem"` the eye starts losing its place
+     * on the return sweep, which costs a learner more on a long comprehension
+     * passage than the empty gutters ever did.
+     *
+     * Keep the default when the player owns the whole page (`h-dvh`, no host
+     * chrome) — that is what it was measured for. Set `"none"` when you mount the
+     * player inside your own layout and your container already supplies the
+     * measure, otherwise learners see a column inside a column.
+     */
+    maxWidth?: string;
+}
 type NodeDetail = {
     type: "choiceSet";
     correctChoiceIds: string[];
@@ -113,6 +140,13 @@ interface ExerciseFeedbackData {
     exerciseId: string;
     questions: QuestionFeedback[];
 }
+/** What the shell needs to open on a finished attempt. See `AssessmentShellProps.review`. */
+interface ShellReview {
+    /** The answers given in the attempt, in the shape `onSubmit` receives them. */
+    answers: AssessmentAnswers;
+    /** The attempt's marking. Drives the score banner and every per-node mark. */
+    result: SubmitResult;
+}
 interface SubmitResult {
     submissionId: string;
     totalScore: number;
@@ -204,6 +238,12 @@ interface EmbedResult {
                         rightId: string;
                     }>;
                 };
+                /**
+                 * The teacher's written feedback on an open response. Only ever present
+                 * in a review (`GET /submissions/{id}/review`), since at submit time no
+                 * teacher has graded anything yet.
+                 */
+                teacher_feedback?: RichContent[];
             }>;
         }>;
     }>;
@@ -241,6 +281,16 @@ interface EdpireAssessmentPlayerProps {
     locale?: ShellLocale;
     /** Branding overrides. Org branding loads from Edpire automatically; pass this to override (white-labelling). */
     branding?: TakeBranding;
+    /**
+     * Geometry of the question column.
+     *
+     * `className` sizes the player's outer box; this sizes the question column
+     * inside it. They are different boxes: by default the questions sit in a
+     * centred 768px reading column whatever the outer box is. Keep that for a
+     * full-page player, pass `{ maxWidth: "none" }` when the player is embedded
+     * in a layout that already constrains width.
+     */
+    layout?: ShellLayout;
     /**
      * When set, the post-submit "View Full Report" button redirects here with
      * `?submission_id=...&score=...&max_score=...` appended. Omit to hide the button.
@@ -343,11 +393,17 @@ interface AssessmentShellProps {
     startedAt?: string;
     /** Called when the learner submits. Should throw on error. */
     onSubmit: (answers: AssessmentAnswers) => Promise<SubmitResult>;
+    /**
+     * Opens the shell on a finished attempt instead of a blank paper: already
+     * submitted, the learner's answers filled in and locked, marking shown. There
+     * is no way to submit from here, so `onSubmit` is never called.
+     */
+    review?: ShellReview;
     /** 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). */
+    /** Called when the learner clicks the back button (shown before submission, and throughout a review). */
     onBack?: () => void;
     /** Custom label for the back button (default: localized "Back"). */
     backLabel?: string;
@@ -360,6 +416,12 @@ interface AssessmentShellProps {
     overlayConfig?: OverlayConfig;
     /** Scope grading/time-up overlays to this component instead of the viewport. */
     contained?: boolean;
+    /**
+     * Geometry of the question column. Omit for the default reading measure,
+     * which is what a full-page player wants. Pass `{ maxWidth: "none" }` when
+     * the shell is embedded inside a host layout that already constrains width.
+     */
+    layout?: ShellLayout;
     /** Media upload handler — required for file-upload and recording modes in
      *  OpenResponse questions. */
     mediaHandler?: QuestionRuntimeProps["mediaHandler"];
@@ -379,6 +441,6 @@ interface AssessmentShellProps {
      */
     fallbackLogoUrl?: string;
 }
-declare function AssessmentShell({ assessment, meta, locale, branding, timeLimitMinutes, startedAt, onSubmit, onViewReport, reportLabel, onBack, backLabel, allowReset, onReset, overlayConfig, contained, onClose, mediaHandler, onAddAnnex, fallbackLogoUrl, }: AssessmentShellProps): react_jsx_runtime.JSX.Element;
+declare function AssessmentShell({ assessment, meta, locale, branding, timeLimitMinutes, startedAt, onSubmit, review, onViewReport, reportLabel, onBack, backLabel, allowReset, onReset, overlayConfig, contained, layout, onClose, mediaHandler, onAddAnnex, fallbackLogoUrl, }: AssessmentShellProps): react_jsx_runtime.JSX.Element;
 
-export { AssessmentShell, type AssessmentShellProps, EdpireAssessmentPlayer, type EdpireAssessmentPlayerProps, EdpireQuestion, type EdpireQuestionProps, type ExerciseFeedbackData, type NodeDetail, type NodeFeedback, type OverlayConfig, type QuestionFeedback, type ShellLocale, type SpinnerTheme, type SubmitResult, type TakeBranding };
+export { AssessmentShell, type AssessmentShellProps, EdpireAssessmentPlayer, type EdpireAssessmentPlayerProps, EdpireQuestion, type EdpireQuestionProps, type ExerciseFeedbackData, type NodeDetail, type NodeFeedback, type OverlayConfig, type QuestionFeedback, type ShellLayout, type ShellLocale, type ShellReview, type SpinnerTheme, type SubmitResult, type TakeBranding };