@lernapps/app-templates 0.0.0-stage → 0.1.0

package/runtime/quiz/quiz.v1.schema.json

@@ -0,0 +1,72 @@
+{
+  "$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]+$"
+        }
+      }
+    }
+  }
+}

package/runtime/quiz/render.ts

@@ -0,0 +1,173 @@
+// Renders the quiz into the page at build time: every question (shared/questions/render.ts) with its controls and,
+// hidden until it is answered, the background of every option, the explanation and further reading; the solutions
+// with the same at the end; the sources; and the data the engine needs. Without JavaScript the page reads as a
+// worksheet with its answer key; with JavaScript the engine (engine.ts) turns it into a quiz, one question at a time.
+// The engine and the end-to-end tests rely on the ids, classes and data attributes written here. A quiz in several
+// languages renders a page per language (renderQuiz with the page's `lang` in its data and the quiz's languages): its
+// texts, the quiz's own texts in that language, and a language switch of plain links before the quiz; German is at the
+// root, every other language below /<language>/. Links to other sites are plain links with rel="noopener", as in the
+// site frame: nothing is loaded from another server before a click.
+import { translator } from "@lernapps/tooling/i18n";
+import de from "./messages/de.json" with { type: "json" };
+import en from "./messages/en.json" with { type: "json" };
+import { renderMaterial, type MaterialContext } from "../shared/blocks/index.ts";
+import { alternateLinks, languageRoot, pageFooter, pageHeader, relative } from "../shared/pages.ts";
+import { localeOf, textsIn, type Language } from "../shared/languages.ts";
+import { QUESTION_MESSAGES } from "../shared/questions/render.ts";
+import { questionId, type Question } from "../shared/questions/question.ts";
+import { solutionId, type Quiz, type QuizData } from "./quiz.ts";
+import { external, renderQuestion, renderSolution } from "../shared/questions/render.ts";
+import { escape } from "../shared/html.ts";
+
+/** The quiz's texts for learners: those of its page, and those of its questions. */
+export type QuizMessages = typeof de & (typeof QUESTION_MESSAGES)["de"];
+/** The quiz's texts for learners in each language it has them: a quiz may declare only these languages. */
+export const QUIZ_MESSAGES: Readonly<Record<Language, QuizMessages>> = {
+  de: { ...QUESTION_MESSAGES.de, ...de },
+  en: { ...QUESTION_MESSAGES.en, ...en },
+};
+
+/** The quiz's texts in `lang`; German for a language it does not have. */
+export const messagesIn = (lang: string): QuizMessages => textsIn(QUIZ_MESSAGES, lang);
+
+/** What rendering in one language needs: its texts and its numbers. */
+interface Words {
+  t: (key: keyof QuizMessages, params?: Readonly<Record<string, string | number>>) => string;
+}
+const languages = new Map<string, Words>();
+function wordsIn(lang = "de"): Words {
+  let found = languages.get(lang);
+  if (found === undefined) {
+    found = { t: translator(messagesIn(lang), localeOf(lang)) };
+    languages.set(lang, found);
+  }
+  return found;
+}
+
+function solutionItem(question: Question, lang: string): string {
+  const { t } = wordsIn(lang);
+  return [
+    `<li class="quiz-solution" id="${solutionId(question)}">`,
+    `<h3>${escape(question.text)}</h3>`,
+    renderSolution(question, { lang }),
+    `<p><a href="#${questionId(question)}">${t("toQuestion")}</a></p>`,
+    `</li>`,
+  ].join("\n");
+}
+
+function renderSources(quiz: Quiz, { t }: Words): string[] {
+  if (quiz.sources === undefined) return [];
+  return [
+    `<section class="quiz-sources" id="quellen">`,
+    `<h2>${t("sources")}</h2>`,
+    `<p>${t("sourcesIntro")}</p>`,
+    `<ul>`,
+    ...quiz.sources.map(
+      (source) =>
+        `<li>${source.url === undefined ? escape(source.title) : external({ title: source.title, url: source.url })}</li>`,
+    ),
+    `</ul>`,
+    `</section>`,
+  ];
+}
+
+/** The pages of a quiz: its languages, German first. */
+export interface QuizPages {
+  languages?: readonly string[];
+  /** Whether a bundled image has no size of its own (see MaterialContext); none is without one. */
+  sizeless?: (image: string) => boolean;
+}
+
+/** One page of the quiz: its title and description, its alternates in its languages for <head>, and its body. */
+export interface RenderedQuiz {
+  title: string;
+  description: string;
+  /** The page in each of the quiz's languages; none while it has one. */
+  alternates: string[];
+  body: string;
+}
+
+/** The form with which the learner chooses how many questions to answer; the engine shows it (none for one question). */
+function renderStart(total: number, t: Words["t"]): string {
+  if (total < 2) return "";
+  return [
+    `<form class="quiz-start" hidden>`,
+    `<p><label for="quiz-count">${t("countLabel")}</label> `,
+    `<input id="quiz-count" type="number" inputmode="numeric" min="1" max="${total}" value="${total}" required> `,
+    `<span>${t("countOf", { total })}</span></p>`,
+    `<p><button type="submit">${t("start")}</button></p>`,
+    `</form>`,
+  ].join("");
+}
+
+/**
+ * The page of the quiz in its data's language (German without one): its title and description, its alternates, and
+ * the quiz itself for the page's body, after a language switch when the quiz has several `languages`.
+ */
+export function renderQuiz(data: QuizData, { languages = ["de"], sizeless }: QuizPages = {}): RenderedQuiz {
+  const { quiz } = data;
+  const lang = data.lang ?? "de";
+  const words = wordsIn(lang);
+  const { t } = words;
+  const where = { path: languageRoot(lang), local: "", languages };
+  // the engine needs the questions to check the answers, not what they show
+  const forEngine = {
+    ...data,
+    quiz: {
+      ...data.quiz,
+      questions: data.quiz.questions.map(({ material: _material, ...question }) => question as Question),
+    },
+  };
+  const json = JSON.stringify(forEngine).replace(/</g, "\\u003c");
+  const material: MaterialContext = {
+    lang,
+    href: (image) => relative(where.path, image),
+    ...(sizeless === undefined ? {} : { sizeless }),
+  };
+  const body = [
+    pageHeader({
+      ...where,
+      lang,
+      label: escape(t("languages")),
+      name: (other) => escape(messagesIn(other).language),
+    }),
+    `<main class="quiz" id="quiz">`,
+    `<h1>${escape(quiz.title)}</h1>`,
+    `<p class="quiz-intro">${escape(quiz.intro)}</p>`,
+    `<p class="quiz-howto">${t("howto")}</p>`,
+    `<noscript><p>${t("noscript")}</p></noscript>`,
+    `<h2 class="quiz-heading">${t("questions")}</h2>`,
+    renderStart(quiz.questions.length, t),
+    `<p class="quiz-progress" hidden></p>`,
+    `<ol class="quiz-questions">`,
+    ...quiz.questions.map((question) =>
+      renderQuestion(question, {
+        element: "li",
+        next: true,
+        lang,
+        ...(question.material === undefined ? {} : { materialHtml: renderMaterial(question.material, material) }),
+      }),
+    ),
+    `</ol>`,
+    `<section class="quiz-result" id="ergebnis" hidden tabindex="-1">`,
+    `<h2>${t("result")}</h2>`,
+    `<p class="quiz-score"></p>`,
+    `<p class="quiz-last" hidden></p>`,
+    `<p><a class="quiz-restart" href="./">${t("restart")}</a></p>`,
+    `</section>`,
+    `<section class="quiz-solutions" id="loesungen">`,
+    `<h2>${t("solutions")}</h2>`,
+    `<ol>`,
+    ...quiz.questions.map((question) => solutionItem(question, lang)),
+    `</ol>`,
+    `</section>`,
+    ...renderSources(quiz, words),
+    `</main>`,
+    pageFooter({ footer: t("footer"), imprint: t("imprint"), privacy: t("privacy") }),
+    `<script type="application/json" id="quiz-data">${json}</script>`,
+  ]
+    .filter((part) => part !== "")
+    .join("\n");
+  const alternates = languages.length < 2 ? [] : alternateLinks(where);
+  return { title: quiz.title, description: quiz.intro, alternates, body };
+}

package/runtime/quiz/validate.ts

@@ -0,0 +1,108 @@
+// Validates a question bank at build time: against its JSON Schema (quiz.v1.schema.json), then what a schema
+// cannot say (unique ids, ...), then each of its questions with the validation of one question
+// (shared/questions/validate.ts). Each problem names the question and what to change, for the assistant that wrote the bank. A bank in several
+// languages declares them (languages, German first): each of its learner texts must then be a map with each of them
+// and no other, with the messages of the explainer's language check.
+import { Ajv2020, type ValidateFunction } from "ajv/dist/2020.js";
+import type { AppChecks } from "../shared/blocks/index.ts";
+import { LANGUAGES, languageListProblems, textLanguages, type Text } from "../shared/languages.ts";
+import {
+  duplicates,
+  inQuestion,
+  questionSchemas,
+  readable,
+  schemaMessages,
+  validateQuestion,
+} from "../shared/questions/validate.ts";
+import schema from "./quiz.v1.schema.json" with { type: "json" };
+import { quizIn, quizLanguages, type Quiz } from "./quiz.ts";
+
+export const SCHEMA_ID = schema.$id;
+/** Where an app finds the schema of its question bank, for the message that names it. */
+export const SCHEMA_FILE = "node_modules/@lernapps/app-templates/runtime/quiz/quiz.v1.schema.json";
+export 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(schema);
+function compiled<T>(ref: string): ValidateFunction<T> {
+  const validate = ajv.getSchema<T>(ref);
+  if (validate === undefined) throw new Error(`the quiz's schema has no ${ref}`);
+  return validate;
+}
+const validateBank = compiled<Quiz<Text>>(SCHEMA_ID);
+
+/** `/questions/2/options/1/text` as `questions[2].options[1].text`, with the id of the question. */
+function inBank(path: string, value: unknown): string {
+  const parts = path.split("/").slice(1);
+  const [first, index] = parts;
+  if (first === "questions" && index !== undefined && /^\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)] : undefined,
+    );
+  }
+  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: Quiz<Text>, languages: readonly string[]): string[] {
+  const texts: [string, Text][] = [
+    ["title", quiz.title],
+    ["intro", quiz.intro],
+    ...(quiz.sources ?? []).map((source, index): [string, Text] => [`sources[${index}].title`, source.title]),
+  ];
+  return texts.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. */
+export function problems(value: unknown, app?: AppChecks): string[] {
+  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. */
+export function readBank(text: string, file: string, app?: AppChecks): Quiz<Text> {
+  let value: unknown;
+  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 as Quiz<Text>;
+}
+
+/** Reads a question bank from JSON text, in German; throws an Error whose message lists every problem. */
+export const parseBank = (text: string, file: string, app?: AppChecks): Quiz => quizIn(readBank(text, file, app), "de");

package/runtime/shared/appname.ts

@@ -0,0 +1,16 @@
+// The app's name from its package.json: the prefix of what it stores on the device (@lernapps/tooling/storage).
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** The name in the package.json of the app in `root`, or `fallback` when there is none. */
+export function appName(root: string, fallback: string): string {
+  try {
+    const manifest: unknown = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    if (typeof manifest === "object" && manifest !== null && "name" in manifest && typeof manifest.name === "string") {
+      return manifest.name;
+    }
+  } catch {
+    // no package.json: the fallback
+  }
+  return fallback;
+}

package/runtime/shared/blocks/block.ts

@@ -0,0 +1,162 @@
+// The blocks that show content, for every archetype that shows it with its questions or on its pages (the quiz, the
+// explainer): a text in restricted Markdown, a formula, a figure (drawn from data, or a bundled image), a labelled
+// figure (a bundled image with labels), a table, a quotation and program code. Their types, the blocks in one
+// language, and the images they use. The checks are in validate.ts, the rendering in render.ts. A bundled image is a
+// file in src/images/ of the app, named by its path from src/: images/<name>.svg (or .png, .jpg, .webp).
+import { inLanguage, type Text } from "../languages.ts";
+import type { CodeLanguage } from "./code.ts";
+
+/** Where a bundled image or a quote comes from: a URL, the same in every language, or a citation, and its licence. */
+export interface Credit<T extends Text = string> {
+  source?: T;
+  licence?: string;
+}
+
+export type Drawing = { kind: "hundred-grid"; filled: number } | { kind: "bar"; part: number; whole: number };
+
+export interface TextBlock<T extends Text = string> {
+  type: "text";
+  text: T;
+}
+
+export interface FormulaBlock<T extends Text = string> {
+  type: "formula";
+  formula: T;
+}
+
+export type Figure<T extends Text = string> = {
+  type: "figure";
+  draw?: Drawing;
+  image?: string;
+  alt: T;
+  caption: T;
+} & Credit<T>;
+
+export type LabelledFigure<T extends Text = string> = {
+  type: "labelled-figure";
+  image: string;
+  alt: T;
+  caption?: T;
+  /** Whether the figure lists the texts of the labels next to the image; without it, alt names every marker. */
+  legend?: boolean;
+  labels: readonly { marker?: string; x: number; y: number; text: T }[];
+} & Credit<T>;
+
+/** The marker of the label at `index`: the one it names, else its number. */
+export const markerOf = (label: { marker?: string }, index: number): string => label.marker ?? String(index + 1);
+
+export interface TableBlock<T extends Text = string> {
+  type: "table";
+  caption: T;
+  header?: readonly T[];
+  rowHeaders?: boolean;
+  rows: readonly (readonly T[])[];
+}
+
+export type QuoteBlock<T extends Text = string> = {
+  type: "quote";
+  text: T;
+  origin: { author: T; work?: T; year?: number | T };
+} & Credit<T>;
+
+export interface CodeBlock<T extends Text = string> {
+  type: "code";
+  language: CodeLanguage;
+  code: string;
+  caption?: T;
+}
+
+/** A block that shows content. */
+export type MaterialBlock<T extends Text = string> =
+  | TextBlock<T>
+  | FormulaBlock<T>
+  | Figure<T>
+  | LabelledFigure<T>
+  | TableBlock<T>
+  | QuoteBlock<T>
+  | CodeBlock<T>;
+
+/** The types of the blocks that show content. */
+export const MATERIAL_TYPES: readonly MaterialBlock["type"][] = [
+  "text",
+  "formula",
+  "figure",
+  "labelled-figure",
+  "table",
+  "quote",
+  "code",
+];
+
+/** The blocks with each text in `lang`. */
+export function materialIn(blocks: readonly MaterialBlock<Text>[], lang: string): MaterialBlock[] {
+  const t = (text: Text) => inLanguage(text, lang);
+  const credit = (block: Credit<Text>): Credit => ({
+    ...(block.source === undefined ? {} : { source: t(block.source) }),
+    ...(block.licence === undefined ? {} : { licence: block.licence }),
+  });
+  return blocks.map((block): MaterialBlock => {
+    switch (block.type) {
+      case "text":
+        return { type: "text", text: t(block.text) };
+      case "formula":
+        return { type: "formula", formula: t(block.formula) };
+      case "figure":
+        return {
+          type: "figure",
+          ...(block.draw === undefined ? {} : { draw: block.draw }),
+          ...(block.image === undefined ? {} : { image: block.image }),
+          alt: t(block.alt),
+          caption: t(block.caption),
+          ...credit(block),
+        };
+      case "labelled-figure":
+        return {
+          type: "labelled-figure",
+          image: block.image,
+          alt: t(block.alt),
+          ...(block.caption === undefined ? {} : { caption: t(block.caption) }),
+          ...(block.legend === undefined ? {} : { legend: block.legend }),
+          labels: block.labels.map((label) => ({
+            ...(label.marker === undefined ? {} : { marker: label.marker }),
+            x: label.x,
+            y: label.y,
+            text: t(label.text),
+          })),
+          ...credit(block),
+        };
+      case "table":
+        return {
+          type: "table",
+          caption: t(block.caption),
+          ...(block.header === undefined ? {} : { header: block.header.map(t) }),
+          ...(block.rowHeaders === undefined ? {} : { rowHeaders: block.rowHeaders }),
+          rows: block.rows.map((row) => row.map(t)),
+        };
+      case "quote":
+        return {
+          type: "quote",
+          text: t(block.text),
+          origin: {
+            author: t(block.origin.author),
+            ...(block.origin.work === undefined ? {} : { work: t(block.origin.work) }),
+            ...(block.origin.year === undefined
+              ? {}
+              : { year: typeof block.origin.year === "number" ? block.origin.year : t(block.origin.year) }),
+          },
+          ...credit(block),
+        };
+      case "code":
+        return {
+          type: "code",
+          language: block.language,
+          code: block.code,
+          ...(block.caption === undefined ? {} : { caption: t(block.caption) }),
+        };
+    }
+  });
+}
+
+/** The bundled images `blocks` use, each once, as paths from src/. */
+export const materialImages = (blocks: readonly MaterialBlock<Text>[]): string[] => [
+  ...new Set(blocks.flatMap((block) => ("image" in block && block.image !== undefined ? [block.image] : []))),
+];