@classytic/labs 0.1.0 → 0.3.0

package/dist/exam/exam-question/core.d.mts

@@ -0,0 +1,90 @@
+import { AnswerSpec } from "../../kit/answer-check.mjs";
+
+//#region src/exam/exam-question/core.d.ts
+/** One thing a mark scheme rewards, worth one mark unless the author says otherwise. */
+interface MarkPoint {
+  /** What earns the mark, in the examiner's words. */
+  text: string;
+  /** Marks for this point. Defaults to 1. */
+  marks?: number;
+}
+/** A wrong answer the author expects, and the misconception behind it. */
+interface CommonError {
+  /** The wrong value or expression a student is likely to produce. */
+  answer: string;
+  /** Why they got it, phrased as the fix rather than the failure. */
+  why: string;
+  /**
+   * This answer is mathematically EQUIVALENT to the correct one, but not in the form the
+   * question demands.
+   *
+   * "Factorise completely" accepts only the complete factorisation; "give your answer in
+   * standard form" accepts only standard form; "express as a product of prime factors" is not
+   * satisfied by the number itself. An equivalence checker cannot see any of that: it says 84
+   * and 2^2 x 3 x 7 are the same, because they are. Flagging the entry makes the lab check it
+   * BEFORE the equivalence test, so the student gets told which form is wanted rather than
+   * being marked right for the answer the question was trying to avoid.
+   */
+  equivalent?: boolean;
+}
+interface ExamPart {
+  /** The part label as the paper prints it: 'a', 'b', 'b(i)'. */
+  label: string;
+  prompt: string;
+  /** Marks available. The sum across parts is the question total. */
+  marks: number;
+  /** The Cambridge command word, which decides what an answer must contain. */
+  command?: 'state' | 'describe' | 'explain' | 'calculate' | 'determine' | 'show that' | 'estimate' | 'suggest' | 'deduce' | 'evaluate';
+  /** The graded answer. Omit for a part that is marked by the scheme alone, e.g. "explain". */
+  answer?: AnswerSpec;
+  /** Unit the answer is expected in, shown beside the input. */
+  unit?: string;
+  /** The marking points, in the order an examiner awards them. */
+  markScheme: MarkPoint[];
+  commonErrors?: CommonError[];
+}
+interface ExamQuestion {
+  /** Where this question comes from or what it imitates. */
+  reference?: string;
+  /** The scenario, shared by every part. */
+  stem: string;
+  parts: ExamPart[];
+}
+/** Total marks available, always derived from the parts so it cannot drift. */
+declare function totalMarks(parts: readonly ExamPart[]): number;
+/**
+ * Marks a mark scheme accounts for, which should equal the part's marks.
+ *
+ * A scheme that does not add up to the marks on offer is an authoring error: the student is told
+ * a part is worth 4 and then shown three things to earn. `examQuestionProblems` reports it.
+ */
+declare function schemeMarks(part: ExamPart): number;
+/** Authoring mistakes worth failing a build over, rather than shipping to a student. */
+declare function examQuestionProblems(question: ExamQuestion): string[];
+type PartVerdict = {
+  state: 'unanswered';
+} | {
+  state: 'correct';
+  marks: number;
+}
+/**
+ * The learner asked to see the mark scheme instead of answering.
+ *
+ * It closes the part like a correct answer does, because a student who is stuck has to be able
+ * to read the scheme and move on, but it earns nothing. Both halves matter: without the first
+ * the question is a dead end, and without the second the marks stop meaning anything.
+ */
+| {
+  state: 'revealed';
+} | {
+  state: 'known-error';
+  why: string;
+} | {
+  state: 'wrong';
+};
+/** Grade one typed response against a part. */
+declare function gradePart(part: ExamPart, raw: string): PartVerdict;
+/** Marks earned so far, for the running total. */
+declare function earnedMarks(parts: readonly ExamPart[], verdicts: Record<string, PartVerdict>): number;
+//#endregion
+export { CommonError, ExamPart, ExamQuestion, MarkPoint, PartVerdict, earnedMarks, examQuestionProblems, gradePart, schemeMarks, totalMarks };

package/dist/exam/exam-question/core.mjs

@@ -0,0 +1,103 @@
+import { checkAnswer, normalizeMathInput } from "../../kit/answer-check.mjs";
+
+//#region src/exam/exam-question/core.ts
+/**
+* Scoring for a structured exam question.
+*
+* Pure and React-free, so the marks a learner sees can be tested directly.
+*
+* The design answers one criticism of concept-first courses: a chapter that ends with a
+* multiple-choice question tests recognition, not production. Here the learner types the answer
+* with no options in front of them, marks are awarded per part the way a mark scheme awards them,
+* and a wrong answer that matches a KNOWN mistake is told which mistake it made rather than just
+* "no". That last part is where the teaching is: "you used the diameter as the radius" moves a
+* student on, and a red cross does not.
+*/
+/** Total marks available, always derived from the parts so it cannot drift. */
+function totalMarks(parts) {
+	return parts.reduce((sum, part) => sum + part.marks, 0);
+}
+/**
+* Marks a mark scheme accounts for, which should equal the part's marks.
+*
+* A scheme that does not add up to the marks on offer is an authoring error: the student is told
+* a part is worth 4 and then shown three things to earn. `examQuestionProblems` reports it.
+*/
+function schemeMarks(part) {
+	return part.markScheme.reduce((sum, point) => sum + (point.marks ?? 1), 0);
+}
+/** Authoring mistakes worth failing a build over, rather than shipping to a student. */
+function examQuestionProblems(question) {
+	const problems = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const part of question.parts) {
+		if (seen.has(part.label)) problems.push(`duplicate part label "${part.label}"`);
+		seen.add(part.label);
+		const scheme = schemeMarks(part);
+		if (scheme !== part.marks) problems.push(`part ${part.label} offers ${part.marks} mark(s) but its scheme accounts for ${scheme}`);
+		for (const slip of part.commonErrors ?? []) {
+			if (!part.answer) continue;
+			const equivalent = checkAnswer(part.answer, slip.answer);
+			if (equivalent && !slip.equivalent) problems.push(`part ${part.label} lists the CORRECT answer "${slip.answer}" as a common error`);
+			if (slip.equivalent && !equivalent) problems.push(`part ${part.label} flags "${slip.answer}" as equivalent, but it is not equal to the answer`);
+		}
+	}
+	return problems;
+}
+/** A part the learner has finished with, whether they answered it or gave up on it. */
+function isSettled(verdict) {
+	return verdict?.state === "correct" || verdict?.state === "revealed";
+}
+/** A normalised string that is a bare number, so `parseFloat` reads ALL of it and not a prefix. */
+const NUMERIC = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i;
+/** Grade one typed response against a part. */
+function gradePart(part, raw) {
+	const trimmed = raw.trim();
+	if (!trimmed) return { state: "unanswered" };
+	const normalized = normalizeMathInput(trimmed).toLowerCase();
+	const slips = part.commonErrors ?? [];
+	for (const slip of slips) if (slip.equivalent && normalized === normalizeMathInput(slip.answer).toLowerCase()) return {
+		state: "known-error",
+		why: slip.why
+	};
+	if (part.answer && checkAnswer(part.answer, trimmed)) return {
+		state: "correct",
+		marks: part.marks
+	};
+	for (const slip of slips) if (normalized === normalizeMathInput(slip.answer).toLowerCase()) return {
+		state: "known-error",
+		why: slip.why
+	};
+	let best = null;
+	if (NUMERIC.test(normalized)) {
+		const a = Number.parseFloat(normalized);
+		for (const slip of slips) {
+			const target = normalizeMathInput(slip.answer).toLowerCase();
+			if (!NUMERIC.test(target)) continue;
+			const b = Number.parseFloat(target);
+			if (!Number.isFinite(a) || !Number.isFinite(b) || b === 0) continue;
+			const distance = Math.abs(a - b) / Math.abs(b);
+			if (distance < .02 && (!best || distance < best.distance)) best = {
+				slip,
+				distance
+			};
+		}
+	}
+	if (best) return {
+		state: "known-error",
+		why: best.slip.why
+	};
+	return { state: "wrong" };
+}
+/** Marks earned so far, for the running total. */
+function earnedMarks(parts, verdicts) {
+	let earned = 0;
+	for (const part of parts) {
+		const verdict = verdicts[part.label];
+		if (verdict?.state === "correct") earned += verdict.marks;
+	}
+	return earned;
+}
+
+//#endregion
+export { earnedMarks, examQuestionProblems, gradePart, isSettled, schemeMarks, totalMarks };

package/dist/exam/exam-question/default-question.d.mts

@@ -0,0 +1,18 @@
+import { ExamPart } from "./core.mjs";
+
+//#region src/exam/exam-question/default-question.d.ts
+/**
+ * The question an author gets when they insert the block with nothing filled in.
+ *
+ * It lives in its own module, importing only a type, so both the manifest (which the authoring
+ * catalog loads) and the runtime preset can use it without the manifest dragging the answer
+ * checker and its expression compiler into the editor's chunk.
+ *
+ * It is deliberately a REAL question rather than lorem: two parts, one graded and one marked by
+ * the scheme alone, with a common error attached, so an author can see every feature the block
+ * has by inserting it once.
+ */
+declare const DEFAULT_EXAM_PARTS: ExamPart[];
+declare const DEFAULT_EXAM_STEM = "A trolley runs at a steady speed along a level track. Air resistance is negligible.";
+//#endregion
+export { DEFAULT_EXAM_PARTS, DEFAULT_EXAM_STEM };

package/dist/exam/exam-question/default-question.mjs

@@ -0,0 +1,41 @@
+//#region src/exam/exam-question/default-question.ts
+/**
+* The question an author gets when they insert the block with nothing filled in.
+*
+* It lives in its own module, importing only a type, so both the manifest (which the authoring
+* catalog loads) and the runtime preset can use it without the manifest dragging the answer
+* checker and its expression compiler into the editor's chunk.
+*
+* It is deliberately a REAL question rather than lorem: two parts, one graded and one marked by
+* the scheme alone, with a common error attached, so an author can see every feature the block
+* has by inserting it once.
+*/
+const DEFAULT_EXAM_PARTS = [{
+	label: "a",
+	prompt: "A trolley travels 12.0 m in 4.0 s at constant speed. Calculate its speed.",
+	marks: 2,
+	command: "calculate",
+	answer: {
+		kind: "number",
+		value: 3
+	},
+	unit: "m/s",
+	markScheme: [{ text: "speed = distance / time" }, { text: "3.0 m/s, to 2 significant figures" }],
+	commonErrors: [{
+		answer: "48",
+		why: "You multiplied. Speed divides distance by time, it does not multiply."
+	}, {
+		answer: "0.33",
+		why: "That is time divided by distance, which is the reciprocal of speed."
+	}]
+}, {
+	label: "b",
+	prompt: "Explain why the trolley travelling at constant speed still has a resultant force of zero.",
+	marks: 2,
+	markScheme: [{ text: "constant speed in a straight line means zero acceleration" }, { text: "and F = ma, so a zero acceleration means a zero resultant force" }],
+	command: "explain"
+}];
+const DEFAULT_EXAM_STEM = "A trolley runs at a steady speed along a level track. Air resistance is negligible.";
+
+//#endregion
+export { DEFAULT_EXAM_PARTS, DEFAULT_EXAM_STEM };

package/dist/exam/exam-question/index.d.mts

@@ -0,0 +1,3 @@
+import { CommonError, ExamPart, ExamQuestion, MarkPoint, PartVerdict, earnedMarks, examQuestionProblems, gradePart, schemeMarks, totalMarks } from "./core.mjs";
+import { ExamQuestion as ExamQuestion$1, ExamQuestionProps } from "./preset.mjs";
+import { DEFAULT_EXAM_PARTS, DEFAULT_EXAM_STEM } from "./default-question.mjs";

package/dist/exam/exam-question/preset.d.mts

@@ -0,0 +1,20 @@
+import { ExamPart } from "./core.mjs";
+import { ReactNode } from "react";
+
+//#region src/exam/exam-question/preset.d.ts
+interface ExamQuestionProps {
+  reference?: string;
+  stem?: string;
+  parts?: ExamPart[];
+  title?: string;
+  activity?: string;
+}
+declare function ExamQuestion({
+  reference,
+  stem,
+  parts,
+  title,
+  activity
+}?: ExamQuestionProps): ReactNode;
+//#endregion
+export { ExamQuestion, ExamQuestionProps };

package/dist/exam/exam-question/preset.mjs

@@ -0,0 +1,198 @@
+'use client';
+
+import { Activity } from "../../kit/activity.mjs";
+import { useCheckpoint } from "../../kit/pedagogy.mjs";
+import { earnedMarks, gradePart, isSettled, totalMarks } from "./core.mjs";
+import { DEFAULT_EXAM_PARTS, DEFAULT_EXAM_STEM } from "./default-question.mjs";
+import { useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+
+//#region src/exam/exam-question/preset.tsx
+/**
+* ExamQuestion, a structured question marked the way a paper is marked.
+*
+* Every other assessment surface in this library is a multiple-choice `Quiz` or a single graded
+* `ask` on a lab. Both test recognition. This one gives the learner a stem, several parts with
+* marks against them, and a box with no options in it. They produce the answer, then see the mark
+* scheme they were being marked against.
+*
+* Three things it does that a quiz cannot:
+*   - awards marks per part, so a 4-mark part is visibly worth more than a 1-mark part;
+*   - names the mistake when a wrong answer matches one the author anticipated, which is the
+*     difference between "no" and "you used the diameter as the radius";
+*   - shows the mark scheme with its acceptable alternatives, so the learner learns what an
+*     examiner is actually looking for rather than only whether the number matched.
+*/
+const markWord = (n) => `${n} mark${n === 1 ? "" : "s"}`;
+/**
+* Print a part label the way a paper prints it.
+*
+* Authors write the label as the syllabus prints it, `a` or `b(ii)`. Wrapping that in brackets
+* blindly gives `(b(ii))`, which no exam paper has ever printed. Cambridge sets the two levels
+* as separate brackets: `(b) (ii)`.
+*/
+const partLabel = (label) => {
+	const open = label.indexOf("(");
+	return open === -1 ? `(${label})` : `(${label.slice(0, open)}) ${label.slice(open)}`;
+};
+function Part({ part, verdict, onGrade }) {
+	const [raw, setRaw] = useState("");
+	const [attempts, setAttempts] = useState(0);
+	const settled = isSettled(verdict);
+	const showScheme = settled || attempts >= 2;
+	return /* @__PURE__ */ jsxs("section", {
+		className: "lab-exam-part",
+		"aria-label": `Part ${part.label}`,
+		children: [
+			/* @__PURE__ */ jsxs("header", {
+				className: "lab-exam-part-head",
+				children: [/* @__PURE__ */ jsx("strong", { children: partLabel(part.label) }), /* @__PURE__ */ jsxs("span", {
+					className: "lab-exam-marks",
+					children: [
+						"[",
+						markWord(part.marks),
+						"]"
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "lab-exam-prompt",
+				children: part.prompt
+			}),
+			part.command ? /* @__PURE__ */ jsxs("p", {
+				className: "lab-exam-command",
+				children: ["Command word: ", /* @__PURE__ */ jsx("strong", { children: part.command })]
+			}) : null,
+			part.answer ? /* @__PURE__ */ jsxs("div", {
+				className: "lab-field-row",
+				children: [
+					/* @__PURE__ */ jsx(Input, {
+						value: raw,
+						placeholder: "your answer",
+						"aria-label": `Answer to part ${part.label}`,
+						disabled: settled,
+						onChange: (e) => setRaw(e.target.value),
+						className: "lab-exam-input"
+					}),
+					part.unit ? /* @__PURE__ */ jsx("span", {
+						className: "lab-exam-unit",
+						children: part.unit
+					}) : null,
+					/* @__PURE__ */ jsx(Button, {
+						type: "button",
+						size: "sm",
+						disabled: settled || !raw.trim(),
+						onClick: () => {
+							setAttempts((n) => n + 1);
+							onGrade(gradePart(part, raw));
+						},
+						children: "Check"
+					}),
+					!settled ? /* @__PURE__ */ jsx(Button, {
+						type: "button",
+						size: "sm",
+						variant: "ghost",
+						className: "lab-exam-reveal",
+						onClick: () => onGrade({ state: "revealed" }),
+						children: "Show mark scheme"
+					}) : null
+				]
+			}) : /* @__PURE__ */ jsx("p", {
+				className: "lab-exam-note",
+				children: "Write your answer on paper, then read the mark scheme and mark it yourself."
+			}),
+			verdict.state === "correct" ? /* @__PURE__ */ jsxs("p", {
+				className: "lab-exam-verdict",
+				"data-tone": "good",
+				children: [
+					"Correct. ",
+					markWord(verdict.marks),
+					" earned."
+				]
+			}) : null,
+			verdict.state === "known-error" ? /* @__PURE__ */ jsxs("p", {
+				className: "lab-exam-verdict",
+				"data-tone": "warn",
+				children: ["Not yet. ", verdict.why]
+			}) : null,
+			verdict.state === "wrong" ? /* @__PURE__ */ jsx("p", {
+				className: "lab-exam-verdict",
+				"data-tone": "bad",
+				children: "Not yet. Check your working, then try again, or show the mark scheme."
+			}) : null,
+			verdict.state === "revealed" ? /* @__PURE__ */ jsx("p", {
+				className: "lab-exam-verdict",
+				"data-tone": "warn",
+				children: "Mark scheme shown. No marks for this part: read it, then try the next one unaided."
+			}) : null,
+			!part.answer || showScheme ? /* @__PURE__ */ jsxs("details", {
+				className: "lab-exam-scheme",
+				open: showScheme,
+				children: [/* @__PURE__ */ jsx("summary", { children: "Mark scheme" }), /* @__PURE__ */ jsx("ul", { children: part.markScheme.map((point, i) => /* @__PURE__ */ jsxs("li", { children: [
+					point.text,
+					" ",
+					/* @__PURE__ */ jsxs("span", {
+						className: "lab-exam-marks",
+						children: [
+							"[",
+							markWord(point.marks ?? 1),
+							"]"
+						]
+					})
+				] }, i)) })]
+			}) : null
+		]
+	});
+}
+function ExamQuestion({ reference, stem = DEFAULT_EXAM_STEM, parts = DEFAULT_EXAM_PARTS, title, activity = "exam-question" } = {}) {
+	const [verdicts, setVerdicts] = useState({});
+	const total = totalMarks(parts);
+	const earned = earnedMarks(parts, verdicts);
+	const allGraded = parts.filter((p) => p.answer).every((p) => isSettled(verdicts[p.label]));
+	const heading = title ?? `${total}-mark structured question`;
+	useCheckpoint({
+		solved: allGraded,
+		activity,
+		score: {
+			raw: earned,
+			max: total
+		}
+	});
+	return /* @__PURE__ */ jsxs(Activity.Root, {
+		className: "lab-exam-question",
+		focusLayout: "compact",
+		children: [
+			/* @__PURE__ */ jsxs(Activity.Header, { children: [/* @__PURE__ */ jsx(Activity.Heading, {
+				eyebrow: reference ?? "Exam practice",
+				title: heading,
+				description: stem
+			}), /* @__PURE__ */ jsx(Activity.FocusButton, {})] }),
+			/* @__PURE__ */ jsxs(Activity.Status, { children: [
+				/* @__PURE__ */ jsxs("strong", { children: [
+					earned,
+					" / ",
+					total
+				] }),
+				/* @__PURE__ */ jsxs("span", { children: [parts.length, " parts"] }),
+				/* @__PURE__ */ jsx("span", { children: "no options given" })
+			] }),
+			/* @__PURE__ */ jsx(Activity.Workspace, { children: /* @__PURE__ */ jsx("div", {
+				className: "lab-exam-parts",
+				children: parts.map((part) => /* @__PURE__ */ jsx(Part, {
+					part,
+					verdict: verdicts[part.label] ?? { state: "unanswered" },
+					onGrade: (verdict) => setVerdicts((v) => ({
+						...v,
+						[part.label]: verdict
+					}))
+				}, part.label))
+			}) }),
+			/* @__PURE__ */ jsxs(Activity.Feedback, { children: [/* @__PURE__ */ jsx("span", { children: "Marks" }), /* @__PURE__ */ jsx("div", { children: "An examiner awards the marks in the scheme, not the final number alone. A right answer with no working can still lose the method marks." })] })
+		]
+	});
+}
+
+//#endregion
+export { ExamQuestion };

package/dist/exam/index.d.mts

@@ -0,0 +1,4 @@
+import { CommonError, ExamPart, ExamQuestion as ExamQuestion$1, MarkPoint, PartVerdict, earnedMarks, examQuestionProblems, gradePart, schemeMarks, totalMarks } from "./exam-question/core.mjs";
+import { ExamQuestion, ExamQuestionProps } from "./exam-question/preset.mjs";
+import { DEFAULT_EXAM_PARTS, DEFAULT_EXAM_STEM } from "./exam-question/default-question.mjs";
+export { type CommonError, DEFAULT_EXAM_PARTS, DEFAULT_EXAM_STEM, type ExamPart, ExamQuestion, type ExamQuestionProps, type ExamQuestion$1 as ExamQuestionSpec, type MarkPoint, type PartVerdict, earnedMarks, examQuestionProblems, gradePart, schemeMarks, totalMarks };

package/dist/exam/index.mjs

@@ -0,0 +1,5 @@
+import { earnedMarks, examQuestionProblems, gradePart, schemeMarks, totalMarks } from "./exam-question/core.mjs";
+import { DEFAULT_EXAM_PARTS, DEFAULT_EXAM_STEM } from "./exam-question/default-question.mjs";
+import { ExamQuestion } from "./exam-question/preset.mjs";
+
+export { DEFAULT_EXAM_PARTS, DEFAULT_EXAM_STEM, ExamQuestion, earnedMarks, examQuestionProblems, gradePart, schemeMarks, totalMarks };