@lernapps/app-templates 0.0.0-stage → 0.1.0

package/dist/quiz-plugin.mjs

@@ -0,0 +1,266 @@
+import { c as textLanguages, o as languageListProblems, r as LANGUAGES, t as escape } from "./html-mffkHGHh.mjs";
+import { r as materialImages } from "./block-BK_ohsH1.mjs";
+import "./blocks-BmRrD7UY.mjs";
+import { a as duplicates, d as readable, f as schemaMessages, o as inQuestion, p as validateQuestion, u as questionSchemas } from "./validate-COaZso7u.mjs";
+import { n as quizLanguages, t as quizIn } from "./quiz-BKc8JYtC.mjs";
+import { t as appName } from "./appname-Bh23cUuz.mjs";
+import { n as isSizeless, t as imageType } from "./image-CspJVfyQ.mjs";
+import { c as withLanguage, i as notFoundPage, n as fromDepth, r as languageRoot } from "./pages-9RaaomoO.mjs";
+import { r as renderQuiz } from "./render-DpRO_RKm.mjs";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+// runtime/quiz/quiz.v1.schema.json
+var quiz_v1_schema_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "urn:lernapps:schema:quiz.v1",
+	title: "Question bank of a lernapps quiz",
+	description: "The questions of a quiz built from the archetype quiz (runtime @lernapps/app-templates), in src/quiz.json: a quiz about things to know. Each option carries short background knowledge, each question links to further reading. The build validates the bank against this schema and fails with a message naming each problem. Every text is for learners: German, plain language, in your own words. A quiz in several languages declares them in languages, German first, and writes every text for learners as a map of texts by language ({ \"de\": …, \"en\": … }) with each of them, and the address of a link as one for every language or as a map by language; the build then writes a page per language.",
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"title",
+		"intro",
+		"questions"
+	],
+	properties: {
+		"$schema": {
+			"description": "This schema, for the editor.",
+			"type": "string"
+		},
+		"languages": {
+			"description": "The languages of the quiz, German first: [\"de\", \"en\"]. The build writes a page per language: German at the root, every other below /<language>/, with a language switch. Each language needs every text for learners as a map of texts by language; without languages, the quiz is German only and its texts are strings.",
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"pattern": "^[a-z]{2}$"
+			},
+			"default": ["de"]
+		},
+		"title": {
+			"description": "The title of the quiz: the page's title and its h1 heading.",
+			"$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+		},
+		"intro": {
+			"description": "One or two sentences under the heading: what the quiz is about and whom it is for.",
+			"$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+		},
+		"rememberLastResult": {
+			"description": "Keep the last result on the learner's device (localStorage, through the preset's storage) and show it at the end. Off by default: then the quiz stores nothing.",
+			"type": "boolean",
+			"default": false
+		},
+		"questions": {
+			"description": "The questions, in the order of the page without JavaScript. With JavaScript, the order is shuffled by the seed in the address (?seed=<number>).",
+			"type": "array",
+			"minItems": 1,
+			"items": { "$ref": "urn:lernapps:schema:question.v1#/$defs/question" }
+		},
+		"sources": {
+			"description": "Where the facts of the quiz come from, listed at the end of the page.",
+			"type": "array",
+			"minItems": 1,
+			"items": { "$ref": "#/$defs/source" }
+		}
+	},
+	$defs: { "source": {
+		"type": "object",
+		"additionalProperties": false,
+		"required": ["title"],
+		"properties": {
+			"title": {
+				"description": "The source, e.g. the article or book.",
+				"$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+			},
+			"url": {
+				"description": "Its address, if it is on the web; https only.",
+				"type": "string",
+				"pattern": "^https://[^\\s]+$"
+			}
+		}
+	} }
+};
+// runtime/quiz/validate.ts
+const SCHEMA_ID = quiz_v1_schema_default.$id;
+/** Where an app finds the schema of its question bank, for the message that names it. */
+const SCHEMA_FILE = "node_modules/@lernapps/app-templates/runtime/quiz/quiz.v1.schema.json";
+const RULE_URL = "https://lernapps.net/tooling/rules/#quiz-bank-valid";
+const ajv = new Ajv2020({
+	allErrors: true,
+	strict: true
+});
+for (const each of questionSchemas) ajv.addSchema(each);
+ajv.addSchema(quiz_v1_schema_default);
+function compiled(ref) {
+	const validate = ajv.getSchema(ref);
+	if (validate === void 0) throw new Error(`the quiz's schema has no ${ref}`);
+	return validate;
+}
+const validateBank = compiled(SCHEMA_ID);
+/** `/questions/2/options/1/text` as `questions[2].options[1].text`, with the id of the question. */
+function inBank(path, value) {
+	const parts = path.split("/").slice(1);
+	const [first, index] = parts;
+	if (first === "questions" && index !== void 0 && /^\d+$/.test(index)) {
+		const questions = typeof value === "object" && value !== null && "questions" in value ? value.questions : [];
+		return inQuestion(`questions[${index}]`, parts.slice(2), Array.isArray(questions) ? questions[Number(index)] : void 0);
+	}
+	const at = readable(parts);
+	return at === "" ? "the bank" : at.slice(1);
+}
+/** Where the quiz declares its languages, for the message about a language it does not declare. */
+const DECLARED_IN = "src/quiz.json";
+/** The problems of the bank's own texts (title, intro, sources) in its languages. */
+function bankTextProblems(quiz, languages) {
+	return [
+		["title", quiz.title],
+		["intro", quiz.intro],
+		...(quiz.sources ?? []).map((source, index) => [`sources[${index}].title`, source.title])
+	].flatMap(([at, text]) => textLanguages(text, languages, false, DECLARED_IN).problems.map((problem) => `${at} (${problem.lang}): ${problem.message}`));
+}
+/** The problems of a question bank; none when it is valid. */
+function problems(value, app) {
+	if (!validateBank(value)) return schemaMessages(validateBank.errors ?? [], (path) => inBank(path, value), value);
+	const languages = quizLanguages(value);
+	const listed = languageListProblems(languages, LANGUAGES).map((problem) => `languages[${Math.max(languages.lastIndexOf(problem.lang), 0)}]: ${problem.message}`);
+	if (listed.length > 0) return listed;
+	const ids = value.questions.map((question) => question.id);
+	return [
+		...duplicates(ids).map((id) => `questions: the id "${id}" appears twice; each question needs its own id`),
+		...bankTextProblems(value, languages),
+		...value.questions.flatMap((question, index) => validateQuestion(question, `questions[${index}]`, languages, DECLARED_IN, app))
+	];
+}
+/** Reads a question bank from JSON text, in all its languages; throws an Error whose message lists every problem. */
+function readBank(text, file, app) {
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch (error) {
+		throw new Error(`${file} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const found = problems(value, app);
+	if (found.length > 0) throw new Error([
+		`${file} is not a valid question bank (${RULE_URL}):`,
+		...found.map((problem) => `  - ${problem}`),
+		`Fix the question bank as its schema says: ${SCHEMA_FILE}`
+	].join("\n"));
+	return value;
+}
+// runtime/quiz/plugin.ts
+/** Where the question bank is, relative to the app's root. */
+const BANK = "src/quiz.json";
+const MARKER = "<!-- quiz -->";
+/** The page in `lang`: the shell with the quiz in that language, its title, description and alternates. */
+function fill(html, { quiz, storage, images }, lang) {
+	if (!html.includes(MARKER)) throw new Error(`index.html has no ${MARKER}: put it in <body>, where the quiz goes`);
+	const data = {
+		quiz: quizIn(quiz, lang),
+		...storage === void 0 ? {} : { storage },
+		...lang === "de" ? {} : { lang }
+	};
+	const { title, description, alternates, body } = renderQuiz(data, {
+		languages: quizLanguages(quiz),
+		sizeless: (image) => {
+			const file = images.get(image);
+			return file !== void 0 && isSizeless(file);
+		}
+	});
+	const head = [
+		`<title>${escape(title)}</title>`,
+		`<meta name="description" content="${escape(description)}" />`,
+		...alternates
+	].join("\n    ");
+	const withHead = /<title>[\s\S]*?<\/title>/.test(html) ? html.replace(/<title>[\s\S]*?<\/title>/, head) : html.replace("</head>", `    ${head}\n  </head>`);
+	return (lang === "de" ? withHead : withLanguage(withHead, lang)).replace(MARKER, () => body);
+}
+/** The language of a page the dev server serves: the first part of its address, if the quiz has that language. */
+function languageOf(url, languages) {
+	const first = /^\/([a-z]{2})\//.exec(url ?? "")?.[1];
+	return first !== void 0 && first !== "de" && languages.includes(first) ? first : "de";
+}
+/** The build step of the quiz: validates the question bank and renders it into index.html, a page per language. */
+function quiz() {
+	let root = process.cwd();
+	let bank;
+	/** The built index.html before the quiz is in it, for the pages in the other languages. */
+	let shell;
+	const load = () => {
+		const file = join(root, BANK);
+		let text;
+		try {
+			text = readFileSync(file, "utf8");
+		} catch {
+			throw new Error(`${BANK} is missing: the quiz's questions belong there (schema quiz.v1.schema.json)`);
+		}
+		const quiz = readBank(text, BANK, { imageExists: (image) => existsSync(join(root, "src", image)) });
+		const images = new Map(quiz.questions.flatMap((question) => materialImages(question.material ?? [])).map((image) => [image, join(root, "src", image)]));
+		return quiz.rememberLastResult === true ? {
+			quiz,
+			storage: appName(root, "quiz"),
+			images
+		} : {
+			quiz,
+			images
+		};
+	};
+	return {
+		name: "lernapps-quiz",
+		enforce: "post",
+		configResolved(config) {
+			root = config.root;
+		},
+		buildStart() {
+			this.addWatchFile(join(root, BANK));
+			try {
+				bank = load();
+			} catch (error) {
+				this.error(error instanceof Error ? error.message : String(error));
+			}
+		},
+		handleHotUpdate({ file, server }) {
+			if (file === join(root, "src/quiz.json")) {
+				bank = void 0;
+				server.ws.send({ type: "full-reload" });
+			}
+		},
+		configureServer(server) {
+			server.middlewares.use((request, response, next) => {
+				const path = decodeURIComponent(new URL(request.url ?? "/", "http://localhost").pathname).replace(/^\//, "");
+				if (!path.startsWith("images/")) return next();
+				const file = (bank ??= load()).images.get(path);
+				if (file === void 0) return next();
+				response.setHeader("content-type", imageType(path));
+				response.end(readFileSync(file));
+			});
+		},
+		transformIndexHtml(html, context) {
+			bank ??= load();
+			shell = html;
+			return fill(html, bank, languageOf(context.originalUrl, quizLanguages(bank.quiz)));
+		},
+		generateBundle() {
+			if (bank === void 0 || shell === void 0) return;
+			this.emitFile({
+				type: "asset",
+				fileName: "404.html",
+				source: notFoundPage()
+			});
+			for (const [image, file] of bank.images) this.emitFile({
+				type: "asset",
+				fileName: image,
+				source: readFileSync(file)
+			});
+			for (const lang of quizLanguages(bank.quiz).slice(1)) {
+				const path = languageRoot(lang);
+				this.emitFile({
+					type: "asset",
+					fileName: `${path}index.html`,
+					source: fill(fromDepth(shell, path), bank, lang)
+				});
+			}
+		}
+	};
+}
+export { BANK, quiz };

package/dist/quiz.mjs

@@ -0,0 +1,246 @@
+import { S as shuffled, g as questionId, u as isCorrect } from "./render-BJey0bwl.mjs";
+import { n as startQuestion } from "./engine-BqF2Vffn.mjs";
+import { a as de_default, i as en_default, r as solutionId } from "./quiz-BKc8JYtC.mjs";
+import { translator } from "@lernapps/tooling/i18n";
+import { announce, moveFocus } from "@lernapps/tooling/a11y";
+import { createStorage } from "@lernapps/tooling/storage";
+// runtime/quiz/engine.ts
+/** The quiz's texts, by the page's language. */
+const BY_LANGUAGE = {
+	de: de_default,
+	en: en_default
+};
+const SEED = "seed";
+const COUNT = "n";
+const isLastResult = (value) => typeof value === "object" && value !== null && "score" in value && "total" in value && typeof value.score === "number" && typeof value.total === "number";
+/** The seed in the address; a new one, written into the address, when there is none. */
+function seedOf(location) {
+	const url = new URL(location.href);
+	const given = Number(url.searchParams.get(SEED));
+	if (Number.isInteger(given) && given > 0) return given;
+	const seed = 1 + Math.floor(Math.random() * 999999);
+	url.searchParams.set(SEED, String(seed));
+	history.replaceState(history.state, "", url);
+	return seed;
+}
+/** The number of questions in the address (?n=<number>), if it is one from 1 to `total`. */
+function countOf(location, total) {
+	const given = Number(new URL(location.href).searchParams.get(COUNT));
+	return Number.isInteger(given) && given >= 1 && given <= total ? given : void 0;
+}
+/** The share of right answers from which the result rains confetti; all right gives fireworks instead. */
+const CONFETTI_FROM = .8;
+/**
+* Celebrates a result on a layer over the page that takes no clicks and is hidden for those who prefer less motion
+* (quiz.css): confetti from 80% right, fireworks for all right. Positions, delays and colours are fixed by index, so
+* the same result always looks the same.
+*/
+function celebrate(root, right, total) {
+	if (total === 0 || right / total < CONFETTI_FROM) return void 0;
+	const layer = root.createElement("div");
+	layer.setAttribute("aria-hidden", "true");
+	const add = (parent, tag, style) => {
+		const element = root.createElement(tag);
+		for (const [name, value] of Object.entries(style)) element.style.setProperty(name, value);
+		parent.append(element);
+		return element;
+	};
+	if (right === total) {
+		layer.className = "quiz-celebration quiz-fireworks";
+		for (const burst of [
+			{
+				left: "24%",
+				top: "26%",
+				delay: "0.3s",
+				hue: 20
+			},
+			{
+				left: "76%",
+				top: "22%",
+				delay: "0.9s",
+				hue: 200
+			},
+			{
+				left: "50%",
+				top: "40%",
+				delay: "1.5s",
+				hue: 320
+			},
+			{
+				left: "18%",
+				top: "58%",
+				delay: "2.1s",
+				hue: 140
+			},
+			{
+				left: "82%",
+				top: "56%",
+				delay: "2.7s",
+				hue: 50
+			}
+		]) {
+			const element = add(layer, "span", {
+				left: burst.left,
+				top: burst.top,
+				"--hue": String(burst.hue)
+			});
+			element.className = "quiz-burst";
+			for (let index = 0; index < 28; index++) {
+				const spark = add(element, "i", {
+					"--angle": `${index * (360 / 28)}deg`,
+					"--far": index % 2 === 0 ? "1" : "0.6"
+				});
+				spark.style.animationDelay = burst.delay;
+			}
+		}
+	} else {
+		layer.className = "quiz-celebration quiz-confetti";
+		for (let index = 0; index < 28; index++) {
+			const piece = add(layer, "span", {
+				left: `${index * 37 % 100}%`,
+				"--hue": String(index * 47 % 360),
+				"--turn": `${(index % 2 === 0 ? 1 : -1) * (180 + index * 29 % 360)}deg`
+			});
+			piece.style.animationDelay = `${index * 53 % 100 / 100}s`;
+		}
+	}
+	root.body.append(layer);
+	return layer;
+}
+/** Starts the quiz on the page the build rendered; does nothing on a page without one. */
+function startQuiz(root = document) {
+	const dataElement = root.getElementById("quiz-data");
+	const main = root.getElementById("quiz");
+	if (!dataElement || !main) return;
+	const { quiz, storage: storageName, lang = "de" } = JSON.parse(dataElement.textContent ?? "{}");
+	const t = translator(BY_LANGUAGE[lang] ?? de_default);
+	const storage = storageName === void 0 ? void 0 : createStorage(storageName);
+	const seed = seedOf(root.location);
+	const total = quiz.questions.length;
+	const shuffledQuestions = shuffled(total, seed).flatMap((index) => quiz.questions[index] ?? []);
+	const hashId = decodeURIComponent(root.location.hash.slice(1));
+	const list = main.querySelector(".quiz-questions");
+	const progress = main.querySelector(".quiz-progress");
+	const result = main.querySelector(".quiz-result");
+	const solutions = main.querySelector(".quiz-solutions");
+	if (!list || !progress || !result || !solutions) return;
+	const heading = main.querySelector(".quiz-heading");
+	const form = main.querySelector(".quiz-start");
+	/** Runs the quiz with the first `count` questions in the order of the seed. */
+	const run = (count) => {
+		const order = shuffledQuestions.slice(0, count);
+		const linked = shuffledQuestions.find((question) => questionId(question) === hashId);
+		if (linked && !order.includes(linked)) order[0] = linked;
+		const answers = /* @__PURE__ */ new Map();
+		main.classList.add("quiz-running");
+		solutions.hidden = true;
+		progress.hidden = false;
+		const items = /* @__PURE__ */ new Map();
+		for (const question of order) {
+			const item = root.getElementById(questionId(question));
+			if (!item) continue;
+			items.set(question.id, item);
+			list.append(item);
+			startQuestion(item, question, {
+				seed,
+				lang,
+				onAnswer: (answer) => answers.set(question.id, answer)
+			});
+		}
+		for (const question of quiz.questions.filter((candidate) => !order.includes(candidate))) {
+			root.getElementById(questionId(question))?.remove();
+			root.getElementById(solutionId(question))?.remove();
+		}
+		let celebration;
+		const show = (index, focus) => {
+			celebration?.remove();
+			order.forEach((question, at) => {
+				const item = items.get(question.id);
+				if (item) item.hidden = at !== index;
+			});
+			result.hidden = true;
+			solutions.hidden = true;
+			progress.textContent = t("progress", {
+				current: index + 1,
+				total: order.length
+			});
+			const legend = items.get(order[index]?.id ?? "")?.querySelector("legend");
+			if (focus && legend) moveFocus(legend);
+			if (focus) progress.scrollIntoView({ block: "start" });
+		};
+		const finish = () => {
+			for (const item of items.values()) item.hidden = true;
+			progress.hidden = true;
+			const right = order.filter((question) => {
+				const answer = answers.get(question.id);
+				return answer !== void 0 && isCorrect(question, answer);
+			}).length;
+			const scoreText = main.querySelector(".quiz-score");
+			if (scoreText) scoreText.textContent = t("score", {
+				score: right,
+				total: order.length
+			});
+			const last = storage?.load("last-result", isLastResult);
+			const lastText = main.querySelector(".quiz-last");
+			if (lastText && last) {
+				lastText.textContent = t("last", {
+					score: last.score,
+					total: last.total
+				});
+				lastText.hidden = false;
+			}
+			storage?.save("last-result", {
+				score: right,
+				total: order.length
+			});
+			const restart = main.querySelector(".quiz-restart");
+			if (restart) restart.href = `?${SEED}=${1 + seed * 7919 % 999999}&${COUNT}=${order.length}`;
+			result.hidden = false;
+			solutions.hidden = false;
+			celebration?.remove();
+			celebration = celebrate(root, right, order.length);
+			moveFocus(result);
+			announce(scoreText?.textContent ?? "");
+		};
+		order.forEach((question, index) => {
+			const next = items.get(question.id)?.querySelector(".question-next");
+			if (!next) return;
+			const isLast = index === order.length - 1;
+			if (isLast) next.textContent = t("toResult");
+			next.addEventListener("click", () => {
+				if (isLast) finish();
+				else show(index + 1, true);
+			});
+		});
+		const fromAddress = (focus) => {
+			const hashId = decodeURIComponent(root.location.hash.slice(1));
+			const index = order.findIndex((question) => questionId(question) === hashId);
+			show(index >= 0 ? index : 0, focus || index >= 0);
+		};
+		globalThis.addEventListener("hashchange", () => fromAddress(true));
+		fromAddress(false);
+	};
+	const given = countOf(root.location, total);
+	if (given !== void 0 || hashId !== "" || !form || total < 2) {
+		run(given ?? total);
+		return;
+	}
+	const input = form.querySelector("input");
+	if (!input) return run(total);
+	list.hidden = true;
+	solutions.hidden = true;
+	if (heading) heading.hidden = true;
+	form.hidden = false;
+	form.addEventListener("submit", (event) => {
+		event.preventDefault();
+		const count = Math.min(total, Math.max(1, Math.floor(Number(input.value)) || total));
+		const url = new URL(root.location.href);
+		url.searchParams.set(COUNT, String(count));
+		history.replaceState(history.state, "", url);
+		form.hidden = true;
+		list.hidden = false;
+		if (heading) heading.hidden = false;
+		run(count);
+	});
+}
+export { startQuiz };