@lernapps/app-templates 0.1.1 → 0.2.1

package/runtime/quiz/e2e.ts

@@ -1,9 +1,14 @@
-// The end-to-end tests of every quiz (@lernapps/app-templates/quiz/e2e), run by `lernapps check --pre-push` on the built
-// app with the app's own question bank. An app's e2e/quiz.e2e.ts is
+// The end-to-end tests of the quiz (@lernapps/app-templates/quiz/e2e), run by `lernapps check --pre-push` on the built
+// app with its own question bank, in two parts. quizTests() tests the app's content, and every app runs it: its
+// e2e/quiz.e2e.ts, part of the scaffold, is
 //
 //   import { quizTests } from "@lernapps/app-templates/quiz/e2e";
 //   quizTests();
 //
+// Each question's link opens it with its text and what it shows, its images loaded; without JavaScript every question
+// and its solution can be read; each other language has its page, its switch, and what a question shows there.
+// quizRuntimeTests() tests the runtime, the same in every app; only this repo runs it, on the template and its
+// fixtures (quiz/e2e/runtime.e2e.ts, not in the scaffold). What follows is what the two parts check together.
 // For each question: its deep link opens it, the right answer counts and a wrong one does not; after either, the
 // background of every option, the explanation and the links for further reading show, the learner's choice marked.
 // The feedback then has the focus and its top is in view, and the button to the next question comes after it.
@@ -37,8 +42,29 @@ const de = QUIZ_MESSAGES.de;
 /** The quiz's own texts in `lang`. */
 const messagesOf = messagesIn;
 
-/** The quiz's tests, for the question bank in `bank` (relative to the app's root). */
+/**
+ * The tests of a quiz's content, for the question bank in `bank` (relative to the app's root): what every app runs
+ * (e2e/quiz.e2e.ts). Each question's link opens it with what it shows; without JavaScript every question and its
+ * solution can be read; each other language has its page. What the runtime does the same in every app is
+ * quizRuntimeTests.
+ */
 export function quizTests(bank = "src/quiz.json"): void {
+  quizSuite(bank, "content");
+}
+
+/**
+ * The tests of the quiz's runtime on the question bank in `bank`: the right answer counts and a wrong one does not, with
+ * the feedback in view; the seed and the order; a run through every question to the full score; how many questions
+ * the learner chooses; what is stored. The template folder and the fixtures of lernapps/app-templates run them
+ * (e2e/runtime.e2e.ts); an app does not, its scaffold has no such file: they test the runtime, which is the same in
+ * every app, and their time grows with the bank (lernapps/app-templates#125).
+ */
+export function quizRuntimeTests(bank = "src/quiz.json"): void {
+  quizSuite(bank, "runtime");
+}
+
+function quizSuite(bank: string, part: "content" | "runtime"): void {
+  const content = part === "content";
   const all = JSON.parse(readFileSync(bank, "utf8")) as Quiz<Text>;
   const languages = quizLanguages(all);
   const quiz = quizIn(all, "de");
@@ -48,94 +74,115 @@ export function quizTests(bank = "src/quiz.json"): void {
     // answer: with motion, every click would wait for a scroll to settle, the run through a quiz grow with its size.
     test.use({ reducedMotion: "reduce" });
 
-    for (const item of quiz.questions) {
-      test(`${item.id} (${item.type}): its link opens it and the right answer counts`, async ({ page }) => {
-        await page.goto(`./#${questionId(item)}`);
-        await expect(question(page, item)).toBeVisible();
-        await expect(page.locator(".question:visible")).toHaveCount(1);
-        await answerQuestion(page, item, rightAnswer(item));
-        await expect(question(page, item).locator(".question-feedback")).toContainText(de.right);
-        await expectFeedbackInView(page, item);
-        // from the feedback, the keyboard reaches the next question (past the links of the background)
-        const next = question(page, item).locator(".question-next");
-        for (let tab = 0; tab < 30 && !(await next.evaluate((button) => button === document.activeElement)); tab++) {
-          await page.keyboard.press("Tab");
-        }
-        await expect(next).toBeFocused();
-        const reveal = question(page, item).locator(".question-reveal");
-        await expectBackground(reveal, item);
-        if (item.type === "single-choice" || item.type === "multiple-choice") {
-          const right = item.options.filter((option) => option.correct).length;
-          await expect(reveal.locator(".question-badge-right")).toHaveCount(right);
-          await expect(reveal.locator(".question-badge-right").first()).toHaveText(de.rightOption);
-        } else {
-          await expect(reveal).toContainText(de.rightAnswer);
-        }
+    if (content) {
+      for (const item of quiz.questions) {
+        test(`${item.id} (${item.type}): its link opens it, with what it shows`, async ({ page }) => {
+          await page.goto(`./#${questionId(item)}`);
+          await expect(question(page, item)).toBeVisible();
+          await expect(page.locator(".question:visible")).toHaveCount(1);
+          await expect(question(page, item).locator("legend")).toHaveText(item.text);
+          if (item.material !== undefined) await expectMaterial(page, item);
+        });
+      }
+
+      test.describe("without JavaScript", () => {
+        test.use({ javaScriptEnabled: false });
+
+        test("every question and its solution can be read", async ({ page }) => {
+          await page.goto("./");
+          for (const item of quiz.questions) {
+            await expect(question(page, item).locator("legend")).toHaveText(item.text);
+            await expectMaterial(page, item, { loaded: false });
+            await expectBackground(page.locator(`#loesung-${item.id}`), item);
+          }
+        });
       });
+    }
+
+    if (!content)
+      for (const item of quiz.questions) {
+        test(`${item.id} (${item.type}): its link opens it and the right answer counts`, async ({ page }) => {
+          await page.goto(`./#${questionId(item)}`);
+          await expect(question(page, item)).toBeVisible();
+          await expect(page.locator(".question:visible")).toHaveCount(1);
+          await answerQuestion(page, item, rightAnswer(item));
+          await expect(question(page, item).locator(".question-feedback")).toContainText(de.right);
+          await expectFeedbackInView(page, item);
+          // from the feedback, the keyboard reaches the next question (past the links of the background)
+          const next = question(page, item).locator(".question-next");
+          for (let tab = 0; tab < 30 && !(await next.evaluate((button) => button === document.activeElement)); tab++) {
+            await page.keyboard.press("Tab");
+          }
+          await expect(next).toBeFocused();
+          const reveal = question(page, item).locator(".question-reveal");
+          await expectBackground(reveal, item);
+          if (item.type === "single-choice" || item.type === "multiple-choice") {
+            const right = item.options.filter((option) => option.correct).length;
+            await expect(reveal.locator(".question-badge-right")).toHaveCount(right);
+            await expect(reveal.locator(".question-badge-right").first()).toHaveText(de.rightOption);
+          } else {
+            await expect(reveal).toContainText(de.rightAnswer);
+          }
+        });
 
-      if (item.material !== undefined) {
-        test(`${item.id} (${item.type}): what it shows is there, and its images load`, async ({ page }) => {
+        test(`${item.id} (${item.type}): a wrong answer does not count`, async ({ page }) => {
           await page.goto(`./#${questionId(item)}`);
-          await expectMaterial(page, item);
+          await answerQuestion(page, item, wrongAnswer(item));
+          await expect(question(page, item).locator(".question-feedback")).toContainText(de.wrong);
+          await expectFeedbackInView(page, item);
+          await expectBackground(question(page, item).locator(".question-reveal"), item);
+          if (item.type === "single-choice" || item.type === "multiple-choice") {
+            await expect(question(page, item).locator(".question-badge-chosen").first()).toHaveText(de.yourChoice);
+          }
         });
       }
 
-      test(`${item.id} (${item.type}): a wrong answer does not count`, async ({ page }) => {
-        await page.goto(`./#${questionId(item)}`);
-        await answerQuestion(page, item, wrongAnswer(item));
-        await expect(question(page, item).locator(".question-feedback")).toContainText(de.wrong);
-        await expectFeedbackInView(page, item);
-        await expectBackground(question(page, item).locator(".question-reveal"), item);
-        if (item.type === "single-choice" || item.type === "multiple-choice") {
-          await expect(question(page, item).locator(".question-badge-chosen").first()).toHaveText(de.yourChoice);
+    if (!content)
+      test("the seed in the address gives the order; without one, the address gets one", async ({ page }) => {
+        const everything = `&n=${quiz.questions.length}`;
+        const order = async (address: string) => {
+          await page.goto(address);
+          return page.locator(".question").evaluateAll((items) => items.map((item) => item.id).join());
+        };
+        const first = await order(`./?seed=11${everything}`);
+        expect(await order(`./?seed=11${everything}`)).toBe(first);
+        if (quiz.questions.length > 2) {
+          const others = [];
+          for (const seed of [12, 13, 14, 15, 16]) others.push(await order(`./?seed=${seed}${everything}`));
+          expect(others.some((other) => other !== first)).toBe(true);
         }
+        await page.goto("./");
+        await expect.poll(() => new URL(page.url()).searchParams.get("seed")).toMatch(/^\d+$/);
       });
-    }
 
-    test("the seed in the address gives the order; without one, the address gets one", async ({ page }) => {
-      const everything = `&n=${quiz.questions.length}`;
-      const order = async (address: string) => {
-        await page.goto(address);
-        return page.locator(".question").evaluateAll((items) => items.map((item) => item.id).join());
-      };
-      const first = await order(`./?seed=11${everything}`);
-      expect(await order(`./?seed=11${everything}`)).toBe(first);
-      if (quiz.questions.length > 2) {
-        const others = [];
-        for (const seed of [12, 13, 14, 15, 16]) others.push(await order(`./?seed=${seed}${everything}`));
-        expect(others.some((other) => other !== first)).toBe(true);
-      }
-      await page.goto("./");
-      await expect.poll(() => new URL(page.url()).searchParams.get("seed")).toMatch(/^\d+$/);
-    });
-
-    test("all right answers give the full score, then the solutions show", async ({ page }) => {
-      await page.goto("./");
-      if (quiz.questions.length > 1) await page.locator(".quiz-start button").click();
-      expect(await page.evaluate(() => Object.keys(localStorage))).toEqual([]);
-      for (let step = 0; step < quiz.questions.length; step++) {
-        const id = await page.locator(".question:visible").getAttribute("data-id");
-        const item = quiz.questions.find((candidate) => candidate.id === id);
-        if (item === undefined) throw new Error(`no visible question at step ${step + 1}`);
-        await answerQuestion(page, item, rightAnswer(item));
-        await question(page, item).locator(".question-next").click();
-      }
-      const total = String(quiz.questions.length);
-      await expect(page.locator(".quiz-score")).toHaveText(
-        de.score.replace("{score}", total).replace("{total}", total),
-      );
-      await expect(page.locator("#loesungen")).toBeVisible();
-      // only the last result, and only when the bank asks for it, under the app's own prefix
-      const stored = await page.evaluate(() => Object.keys(localStorage));
-      if (quiz.rememberLastResult === true) {
-        expect(stored).toHaveLength(1);
-        expect(stored[0]).toMatch(/^lernapps:.+:last-result$/);
-      } else {
-        expect(stored).toEqual([]);
-      }
-    });
+    if (!content)
+      test("all right answers give the full score, then the solutions show", async ({ page }) => {
+        await page.goto("./");
+        if (quiz.questions.length > 1) await page.locator(".quiz-start button").click();
+        expect(await page.evaluate(() => Object.keys(localStorage))).toEqual([]);
+        for (let step = 0; step < quiz.questions.length; step++) {
+          const id = await page.locator(".question:visible").getAttribute("data-id");
+          const item = quiz.questions.find((candidate) => candidate.id === id);
+          if (item === undefined) throw new Error(`no visible question at step ${step + 1}`);
+          await answerQuestion(page, item, rightAnswer(item));
+          await question(page, item).locator(".question-next").click();
+        }
+        const total = String(quiz.questions.length);
+        await expect(page.locator(".quiz-score")).toHaveText(
+          de.score.replace("{score}", total).replace("{total}", total),
+        );
+        await expect(page.locator("#loesungen")).toBeVisible();
+        // only the last result, and only when the bank asks for it, under the app's own prefix
+        const stored = await page.evaluate(() => Object.keys(localStorage));
+        if (quiz.rememberLastResult === true) {
+          expect(stored).toHaveLength(1);
+          expect(stored[0]).toMatch(/^lernapps:.+:last-result$/);
+        } else {
+          expect(stored).toEqual([]);
+        }
+      });
 
-    if (quiz.questions.length > 1) {
+    if (!content && quiz.questions.length > 1) {
       test("the learner chooses how many questions to answer; the address keeps the choice", async ({ page }) => {
         await page.goto("./?seed=11");
         await expect(page.locator(".quiz-start")).toBeVisible();
@@ -163,70 +210,60 @@ export function quizTests(bank = "src/quiz.json"): void {
       });
     }
 
-    test.describe("without JavaScript", () => {
-      test.use({ javaScriptEnabled: false });
-
-      test("every question and its solution can be read", async ({ page }) => {
-        await page.goto("./");
-        for (const item of quiz.questions) {
-          await expect(question(page, item).locator("legend")).toHaveText(item.text);
-          await expectMaterial(page, item, { loaded: false });
-          await expectBackground(page.locator(`#loesung-${item.id}`), item);
-        }
-      });
-    });
-
     for (const lang of languages.slice(1)) {
       const local = quizIn(all, lang);
       const words = messagesOf(lang);
       const address = `./${lang}/`;
 
       test.describe(`in ${lang}`, () => {
-        test.describe("without JavaScript", () => {
-          test.use({ javaScriptEnabled: false });
-
-          test(`the page is in ${lang}, every question and its solution can be read, the switch leads to every language`, async ({
-            page,
-          }) => {
-            await page.goto(address);
-            await expect(page.locator("html")).toHaveAttribute("lang", lang);
-            await expect(page.locator("h1")).toHaveText(local.title);
-            await expect(page.locator("#loesungen h2")).toHaveText(words.solutions);
-            for (const item of local.questions) {
-              await expect(question(page, item).locator("legend")).toHaveText(item.text);
-              await expectMaterial(page, item, { loaded: false });
-              await expectBackground(page.locator(`#loesung-${item.id}`), item);
-            }
-            for (const other of languages) {
-              await expect(page.locator(`link[rel="alternate"][hreflang="${other}"]`)).toHaveCount(1);
-            }
-            for (const other of languages.filter((candidate) => candidate !== lang)) {
+        if (content)
+          test.describe("without JavaScript", () => {
+            test.use({ javaScriptEnabled: false });
+
+            test(`the page is in ${lang}, every question and its solution can be read, the switch leads to every language`, async ({
+              page,
+            }) => {
               await page.goto(address);
-              await page.locator(`.page-languages a[hreflang="${other}"]`).click();
-              await expect(page.locator("html")).toHaveAttribute("lang", other);
-              await expect(page.locator("h1")).toHaveText(quizIn(all, other).title);
-              await expect(page.locator('.page-languages a[aria-current="page"]')).toHaveAttribute("hreflang", other);
-            }
+              await expect(page.locator("html")).toHaveAttribute("lang", lang);
+              await expect(page.locator("h1")).toHaveText(local.title);
+              await expect(page.locator("#loesungen h2")).toHaveText(words.solutions);
+              for (const item of local.questions) {
+                await expect(question(page, item).locator("legend")).toHaveText(item.text);
+                await expectMaterial(page, item, { loaded: false });
+                await expectBackground(page.locator(`#loesung-${item.id}`), item);
+              }
+              for (const other of languages) {
+                await expect(page.locator(`link[rel="alternate"][hreflang="${other}"]`)).toHaveCount(1);
+              }
+              for (const other of languages.filter((candidate) => candidate !== lang)) {
+                await page.goto(address);
+                await page.locator(`.page-languages a[hreflang="${other}"]`).click();
+                await expect(page.locator("html")).toHaveAttribute("lang", other);
+                await expect(page.locator("h1")).toHaveText(quizIn(all, other).title);
+                await expect(page.locator('.page-languages a[aria-current="page"]')).toHaveAttribute("hreflang", other);
+              }
+            });
           });
-        });
 
-        test(`what a question shows, in ${lang}`, async ({ page }) => {
-          const item = local.questions.find((candidate) => candidate.material !== undefined);
-          test.skip(item === undefined, "no question shows content");
-          if (item === undefined) return;
-          await page.goto(`${address}#${questionId(item)}`);
-          await expectMaterial(page, item);
-        });
+        if (content)
+          test(`what a question shows, in ${lang}`, async ({ page }) => {
+            const item = local.questions.find((candidate) => candidate.material !== undefined);
+            test.skip(item === undefined, "no question shows content");
+            if (item === undefined) return;
+            await page.goto(`${address}#${questionId(item)}`);
+            await expectMaterial(page, item);
+          });
 
-        test(`one question, answered in ${lang}`, async ({ page }) => {
-          const item = local.questions[0];
-          if (item === undefined) throw new Error("the quiz has no questions");
-          await page.goto(`${address}#${questionId(item)}`);
-          await expect(question(page, item)).toBeVisible();
-          await answerQuestion(page, item, rightAnswer(item), lang);
-          await expect(question(page, item).locator(".question-feedback")).toContainText(words.right);
-          await expectBackground(question(page, item).locator(".question-reveal"), item);
-        });
+        if (!content)
+          test(`one question, answered in ${lang}`, async ({ page }) => {
+            const item = local.questions[0];
+            if (item === undefined) throw new Error("the quiz has no questions");
+            await page.goto(`${address}#${questionId(item)}`);
+            await expect(question(page, item)).toBeVisible();
+            await answerQuestion(page, item, rightAnswer(item), lang);
+            await expect(question(page, item).locator(".question-feedback")).toContainText(words.right);
+            await expectBackground(question(page, item).locator(".question-reveal"), item);
+          });
       });
     }
   });

package/scaffold/explainer/src/app.yaml

@@ -0,0 +1,5 @@
+# yaml-language-server: $schema=../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json
+title: Platzhalter
+intro: Dieses Kapitel hält den Platz frei, bis der geplante Inhalt da ist.
+languages: [de]
+chapters: [thema]

package/scaffold/explainer/src/thema/chapter.yaml

@@ -0,0 +1,4 @@
+# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json
+title: Thema
+summary: Ersetze dieses Kapitel durch das erste geplante.
+pages: [einstieg]

package/scaffold/explainer/src/thema/einstieg.yaml

@@ -0,0 +1,28 @@
+# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json
+title: Einstieg
+description: Eine Seite, die den Platz frei hält.
+blocks:
+  - type: section
+    id: worum-es-geht
+    title: Worum es geht
+    blocks:
+      - type: text
+        text: Ersetze diese Seite durch die erste geplante.
+  - type: section
+    id: uebung
+    title: Übung
+    blocks:
+      - type: single-choice
+        id: platzhalter
+        text: Welche Antwort ist richtig?
+        explanation: Diese Übung ist ein Platzhalter. Ersetze sie durch die erste geplante.
+        links:
+          - title: lernapps.net
+            url: https://lernapps.net/
+        options:
+          - text: Diese
+            correct: true
+            info: "Richtig: Diese Antwort ist als richtig markiert."
+          - text: Diese nicht
+            correct: false
+            info: "Falsch: Diese Antwort ist als falsch markiert."

package/scaffold/interactive/src/app.yaml

@@ -0,0 +1,8 @@
+# yaml-language-server: $schema=../node_modules/@lernapps/app-templates/runtime/interactive/interactive.v1.schema.json
+title: Platzhalter
+description: Ein Knopf, der bis drei zählt. Er hält den Platz frei, bis die geplante App da ist.
+howto: |
+  - Drücke „Weiter“, bis du bei drei bist.
+competencies:
+  - Ich kann bis drei zählen.
+languages: [de]

package/scaffold/interactive/src/core/index.ts

@@ -0,0 +1,25 @@
+// The app's logic, a placeholder: a count from 0 to the goal of src/data/count.json, one step for each "weiter" (the
+// button of the component).
+// Pure TypeScript without DOM; the runtime keeps the state and calls start and step
+// (@lernapps/app-templates/interactive). Replace it with the planned core.
+import type { Input } from "@lernapps/app-templates/interactive";
+import count from "../data/count.json" with { type: "json" };
+
+export interface State {
+  seed: number;
+  count: number;
+  done: boolean;
+}
+
+/** How far the count goes. */
+export const GOAL: number = count.goal;
+
+export function start(seed: number): State {
+  return { seed, count: 0, done: false };
+}
+
+export function step(state: State, input: Input): State {
+  if (state.done || input.kind !== "action" || input.name !== "weiter") return state;
+  const count = state.count + 1;
+  return { ...state, count, done: count >= GOAL };
+}

package/scaffold/interactive/src/data/count.json

@@ -0,0 +1 @@
+{ "goal": 3 }

package/scaffold/interactive/src/messages/de.json

@@ -0,0 +1,6 @@
+{
+  "app": "Zähler",
+  "count": "{count} von {goal}",
+  "next": "Weiter",
+  "done": "Fertig: bis drei gezählt."
+}

package/scaffold/interactive/src/playthroughs/zaehlen.yaml

@@ -0,0 +1,12 @@
+# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/interactive/playthrough.v1.schema.json
+# Three times "weiter": the count reaches three and the app is done; a fourth press changes nothing.
+seed: 1
+steps:
+  - inputs: [{ kind: action, name: weiter }]
+    state: { count: 1, done: false }
+    announce: 1 von 3
+  - inputs: [{ kind: action, name: weiter }, { kind: action, name: weiter }]
+    state: { count: 3, done: true }
+    announce: "Fertig: bis drei gezählt."
+  - inputs: [{ kind: action, name: weiter }]
+    state: { count: 3, done: true }

package/scaffold/interactive/src/ui/App.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+// A placeholder: the count and a button that emits the action "weiter". Replace it with the planned component.
+import { watch } from "vue";
+import { announce } from "@lernapps/tooling/a11y";
+import { translator } from "@lernapps/tooling/i18n";
+import type { Input } from "@lernapps/app-templates/interactive";
+import { GOAL, type State } from "../core/index.ts";
+import de from "../messages/de.json";
+
+const props = defineProps<{ state: State; lang: string }>();
+const emit = defineEmits<{ input: [input: Input] }>();
+const t = translator(de);
+
+watch(
+  () => props.state.count,
+  (count) => announce(props.state.done ? t("done") : t("count", { count, goal: GOAL })),
+);
+</script>
+
+<template>
+  <section :aria-label="t('app')">
+    <p>{{ state.done ? t("done") : t("count", { count: state.count, goal: GOAL }) }}</p>
+    <button v-if="!state.done" type="button" @click="emit('input', { kind: 'action', name: 'weiter' })">
+      {{ t("next") }}
+    </button>
+  </section>
+</template>

package/scaffold/quiz/src/quiz.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "../node_modules/@lernapps/app-templates/runtime/quiz/quiz.v1.schema.json",
+  "title": "Platzhalter",
+  "intro": "Diese Frage hält den Platz frei, bis die geplanten Fragen da sind.",
+  "questions": [
+    {
+      "id": "platzhalter",
+      "type": "single-choice",
+      "text": "Welche Antwort ist richtig?",
+      "options": [
+        {
+          "text": "Diese",
+          "correct": true,
+          "info": "Richtig: Diese Antwort ist als richtig markiert."
+        },
+        {
+          "text": "Diese nicht",
+          "correct": false,
+          "info": "Falsch: Diese Antwort ist als falsch markiert."
+        }
+      ],
+      "explanation": "Diese Frage ist ein Platzhalter. Sie zeigt, wie eine Frage aufgebaut ist, und wird durch die erste geplante ersetzt.",
+      "links": [
+        {
+          "title": "lernapps.net",
+          "url": "https://lernapps.net/"
+        }
+      ]
+    }
+  ]
+}