@lernapps/app-templates 0.2.1 → 0.3.0

package/runtime/explainer/plugin.ts

@@ -12,7 +12,8 @@
 // depth. The bundled images go to images/, the tutor page of each content page to <chapter>/<page>/tutor/ with its
 // Markdown beside it (index.md; tutorpage.ts), and of each self-assessment to <assessment>/tutor/ (assessment-page.ts),
 // every link of them checked, and 404.html, which leads every address the
-// app does not have to its start page (notFoundPage of ../shared/pages.ts). `vp dev` serves the same pages and tutor pages, rendered on each request.
+// app does not have to its start page (notFoundPage of ../shared/pages.ts). An app of format 2 also gets
+// lernapps-pages.json at the root, the list of its pages with their competencies for the catalog (page-list.ts). `vp dev` serves the same pages and tutor pages, rendered on each request.
 //
 // Components (src/components/<Name>.vue, components.ts): only when the app has them, the plugin compiles them with
 // @vitejs/plugin-vue and resolves vue to the copy this runtime depends on, so that the components and the islands
@@ -53,6 +54,7 @@ import {
   tutorPageDocument,
 } from "./tutorpage.ts";
 import { imageType } from "../shared/blocks/image.ts";
+import { PAGE_LIST, pageList } from "./page-list.ts";
 
 const MARKER = "<!-- explainer -->";
 const ISLANDS = "\0lernapps-explainer-islands";
@@ -263,7 +265,9 @@ export function explainer(): Plugin[] {
       }
       if (command !== "build" || content.components.length === 0) return;
       const rendered = await withServer(root, (loader) => renderComponents(content, loader, true));
-      if (rendered.problems.length > 0) this.error(new ContentError(rendered.problems).message);
+      if (rendered.problems.length > 0) {
+        this.error(new ContentError(rendered.problems, content.app.format ?? 1).message);
+      }
       islands = rendered.islands;
       descriptions = rendered.descriptions;
       islandsChunk = this.emitFile({ type: "chunk", id: ISLANDS, name: "islands" });
@@ -289,6 +293,11 @@ export function explainer(): Plugin[] {
         else this.emitFile({ type: "asset", fileName: `${page.route.path}index.html`, source: html });
       }
       this.emitFile({ type: "asset", fileName: "404.html", source: notFoundPage() });
+      // format 2: the list of the pages for the catalog
+      const list = pageList(content);
+      if (list !== undefined) {
+        this.emitFile({ type: "asset", fileName: PAGE_LIST, source: `${JSON.stringify(list, null, 2)}\n` });
+      }
       for (const [image, file] of content.images) {
         this.emitFile({ type: "asset", fileName: image, source: readFileSync(file) });
       }
@@ -404,7 +413,7 @@ export function explainer(): Plugin[] {
           );
         }
       }
-      if (problems.length > 0) this.error(new ContentError(problems).message);
+      if (problems.length > 0) this.error(new ContentError(problems, content.app.format ?? 1).message);
     },
     configureServer(server) {
       devServer = server;
@@ -442,7 +451,7 @@ export function explainer(): Plugin[] {
         if (dev === undefined) return next();
         renderComponents(content, (id) => dev.ssrLoadModule(id), false)
           .then(({ islands: rendered, descriptions: described, problems }) => {
-            if (problems.length > 0) throw new ContentError(problems);
+            if (problems.length > 0) throw new ContentError(problems, content.app.format ?? 1);
             if (forScope) {
               const markdown = path.endsWith(TUTOR_MARKDOWN);
               const lang =

package/runtime/explainer/render.ts

@@ -2,7 +2,8 @@
 // as inline SVG or an image, tables, timelines, definitions, quotes, highlighted code, the exercises (exercises.ts:
 // each with its solution in a <details>, a generated one with three worked tasks), and the navigation (contents,
 // breadcrumbs, previous and next, the contents of a page with three or more sections, the glossary, the language
-// switch). Without JavaScript the page is complete; the client module only adds. A vue-component block is its island:
+// switch; a recap page marked in the contents, and at its top its notice with the link to the learning map). Without
+// JavaScript the page is complete; the client module only adds. A vue-component block is its island:
 // the component's markup as the build rendered it (`hidden` until it hydrates), its nojs text, its props in the page's
 // language, and for an exercise its anchor, its task number with "Neue Aufgabe", the task of number 1 as its describe
 // states it with the solution folded, and the place of its feedback. Links to other sites are plain links with rel="noopener":
@@ -13,6 +14,7 @@ import { questionMessagesIn } from "../shared/questions/render.ts";
 import { propsIn } from "./components/props.ts";
 import {
   inLanguage,
+  mapUrl,
   termId as termIdOf,
   timelineEvents,
   type Block,
@@ -322,7 +324,10 @@ function pageList(context: Context, pages: readonly NonNullable<Route["page"]>[]
         page.description === undefined
           ? ""
           : ` <span class="explainer-description">${context.text(page.description)}</span>`;
-      return `<li><a href="${context.to(`${page.chapter}/${page.id}/`)}">${context.text(page.title)}</a>${description}</li>`;
+      // a recap page repeats a competency the app does not practise: marked, so that no one takes it for the app's own
+      const recap =
+        page.recap === undefined ? "" : ` <span class="explainer-recap-note">(${plain(context.t("recapNote"))})</span>`;
+      return `<li><a href="${context.to(`${page.chapter}/${page.id}/`)}">${context.text(page.title)}</a>${recap}${description}</li>`;
     })
     .join("")}</ol>`;
 }
@@ -407,6 +412,7 @@ function main(context: Context): string {
         title,
         tutorSection(context),
         `</div>`,
+        page.recap === undefined ? "" : recapNotice(context, page.recap),
         pageContents(context, page.blocks),
         renderBlocks(context, page.blocks, 1),
       ].join("\n");
@@ -414,6 +420,24 @@ function main(context: Context): string {
   }
 }
 
+/**
+ * At the top of a recap page: that it is a recap, and the link to the competency's page on the learning map, where the
+ * apps are that practise it. The runtime writes it, so that it cannot be missing; a plain link, nothing loaded before
+ * a click.
+ */
+function recapNotice(context: Context, recap: string): string {
+  const link = external(mapUrl(recap), context.t("recapLink"));
+  // the message keeps its placeholder {link} unfilled: the link goes in its place as markup
+  const [before = "", after = ""] = context.t("recapText").split("{link}");
+  const label = plain(context.t("recap"));
+  return [
+    `<aside class="explainer-recap" aria-label="${label}">`,
+    `<p class="explainer-recap-label">${label}</p>`,
+    `<p>${plain(before)}${link}${plain(after)}</p>`,
+    `</aside>`,
+  ].join("\n");
+}
+
 /** What a part of a self-assessment needs of the page it is on (assessment-page.ts). */
 const assessmentContext = (context: Context): AssessmentContext => ({
   site: context.site,

package/runtime/explainer/schema.ts

@@ -1,25 +1,35 @@
-// The explainer's content schema (explainer.v1.schema.json) at build time: the validators of its files (the app, a
-// chapter, a page, a data file), and the explainer's own words for the errors of the schema (what a quote or a bundled
+// The explainer's content schemas at build time: format 1 (explainer.v1.schema.json) and format 2
+// (explainer.v2.schema.json, which adds the strand of the app, the competencies of each page and recap pages, and refers to format 1
+// for everything else); the validators of their files (the app, a chapter, a page, a data file) by format, and the explainer's own words for the errors of the schema (what a quote or a bundled
 // image lacks, which fields a block type has, which an exercise of a question type); the general messages are
 // shared/content.ts's.
 import { Ajv2020, type ValidateFunction } from "ajv/dist/2020.js";
 import schema from "./explainer.v1.schema.json" with { type: "json" };
+import schemaV2 from "./explainer.v2.schema.json" with { type: "json" };
 import questionSchema from "../shared/questions/question.v1.schema.json" with { type: "json" };
 import { knownProperties, schemasById } from "../shared/schema.ts";
 import { addressProblem, QUESTION_BRANCH, questionSchemas } from "../shared/questions/validate.ts";
 import { isObject, schemaProblems, type DescribeError, type Problems, type YamlFile } from "../shared/content.ts";
 
 export const SCHEMA_ID = schema.$id;
-/** Where an app finds the schema of its content, for the message that names it. */
-export const SCHEMA_FILE = "node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json";
+export const SCHEMA_ID_V2 = schemaV2.$id;
+/** The formats of the content: 1 without `format` in src/app.yaml, 2 with `format: 2`. */
+export type Format = 1 | 2;
+/** Where an app finds the schema of its content, by format, for the message that names it. */
+export const SCHEMA_FILES: Readonly<Record<Format, string>> = {
+  1: "node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json",
+  2: "node_modules/@lernapps/app-templates/runtime/explainer/explainer.v2.schema.json",
+};
+export const SCHEMA_FILE = SCHEMA_FILES[1];
 
 // union types ("type": ["string", "object"]) keep the messages of the comparator and the lists plain
 const ajv = new Ajv2020({ allErrors: true, strict: true, allowUnionTypes: true });
 for (const each of questionSchemas) ajv.addSchema(each);
 ajv.addSchema(schema);
-const validator = (name: string): ValidateFunction => {
-  const validate = ajv.getSchema(`${SCHEMA_ID}#/$defs/${name}`);
-  if (validate === undefined) throw new Error(`the schema has no $defs/${name}`);
+ajv.addSchema(schemaV2);
+const validator = (name: string, id = SCHEMA_ID): ValidateFunction => {
+  const validate = ajv.getSchema(`${id}#/$defs/${name}`);
+  if (validate === undefined) throw new Error(`the schema ${id} has no $defs/${name}`);
   return validate;
 };
 export const validators = {
@@ -29,6 +39,20 @@ export const validators = {
   data: validator("data"),
   event: validator("event"),
 };
+/** The validators of format 2: its own app and page; chapters, data files and events are those of format 1. */
+const validatorsV2: typeof validators = {
+  ...validators,
+  app: validator("app", SCHEMA_ID_V2),
+  page: validator("page", SCHEMA_ID_V2),
+};
+
+/** The format of the app `app` (src/app.yaml as read): 2 when it names any format, which its schema then checks. */
+export const formatOf = (app: unknown): Format => (isObject(app) && app["format"] !== undefined ? 2 : 1);
+
+/** The fields of format 2, which format 1 does not know. */
+const FORMAT_2_FIELDS = new Set(["format", "strand", "competencies", "recap"]);
+/** The fields of format 2 on a page. */
+const PAGE_FIELDS = new Set(["competencies", "recap"]);
 
 const schemas = schemasById(...questionSchemas, schema);
 
@@ -61,6 +85,9 @@ const questionFields = (type: string): Set<string> => {
 /** What `required` names as missing, with why it is needed. */
 function missing(property: string, object: unknown): string {
   const type = isObject(object) ? object["type"] : undefined;
+  if (property === "strand") {
+    return "strand is missing; name the strand of the learning map the app stays in, <subject>/<strand> (e.g. mathematik/stochastik), or none when the app is on no strand";
+  }
   if (property === "origin") return "origin is missing; a quote names who said or wrote it, where and when";
   if ((property === "licence" || property === "source") && type === "quote") {
     return `${property} is missing; a quote names its source and its licence`;
@@ -80,7 +107,58 @@ const describe: DescribeError = (error, path, value) => {
       const { lang, message } = addressProblem(value);
       return { message, ...(lang === undefined ? {} : { lang }) };
     }
+    case "not":
+      // a page with both: it practises competencies of the app's strand, or it repeats one the app does not practise
+      if (path.length !== 0 || !isObject(value) || !("recap" in value) || !("competencies" in value)) return undefined;
+      return {
+        path: ["recap"],
+        message:
+          "a page has competencies or recap, never both: a page practises competencies of the app's strand, a recap page only repeats a competency the app does not practise; remove one of them",
+      };
+    case "const":
+      // the format of the content: 2, or none at all for format 1
+      if (path.length !== 1 || path[0] !== "format") return undefined;
+      return { message: `${String(value)} is not a format; write format: 2, or leave format out for format 1` };
+    case "uniqueItems":
+      if (path.at(-1) !== "competencies") return undefined;
+      return { message: "names a competency twice; name each competency once" };
+    case "additionalProperties": {
+      // a field of format 2 in an app of format 1
+      const property = String(error.params["additionalProperty"]);
+      if (path.length !== 0 || !FORMAT_2_FIELDS.has(property) || !isObject(value)) return undefined;
+      if (PAGE_FIELDS.has(property) && "blocks" in value) {
+        return {
+          path: [property],
+          message: `${property} is a field of format 2; add format: 2 and the app's strand to src/app.yaml, or remove it`,
+        };
+      }
+      if (!PAGE_FIELDS.has(property) && "chapters" in value) {
+        return {
+          path: [property],
+          message: `${property} is a field of format 2; add format: 2 to src/app.yaml, with the app's strand`,
+        };
+      }
+      return undefined;
+    }
     case "pattern":
+      // the strand of the app: <subject>/<strand> or none
+      if (path.length === 1 && path[0] === "strand") {
+        return {
+          message: `${String(value)} is no strand; write <subject>/<strand> with the ids of the learning map, e.g. mathematik/stochastik, or none`,
+        };
+      }
+      // the competency a recap page repeats: <subject>/<competency>
+      if (path.length === 1 && path[0] === "recap") {
+        return {
+          message: `${String(value)} is no competency of the learning map; write <subject>/<competency> with the ids of the learning map, e.g. physik/gewichtskraft-berechnen`,
+        };
+      }
+      // a competency of a page: an id of the learning map
+      if (path.at(-2) === "competencies") {
+        return {
+          message: `${String(value)} is no competency id; use the competency's id in the learning map: lower-case letters, digits and hyphens, e.g. laplace`,
+        };
+      }
       // an exercise of a self-assessment: by its page and id
       if (path.at(-2) === "exercises" && path[0] === "selfAssessment") {
         return { message: `${String(value)} is no exercise's address; write /<chapter>/<page>/#<exercise>` };
@@ -129,8 +207,13 @@ const describe: DescribeError = (error, path, value) => {
   return undefined;
 };
 
-export function validate(yaml: YamlFile, kind: keyof typeof validators, problems: Problems): boolean {
-  const check = validators[kind];
+export function validate(
+  yaml: YamlFile,
+  kind: keyof typeof validators,
+  problems: Problems,
+  format: Format = 1,
+): boolean {
+  const check = (format === 2 ? validatorsV2 : validators)[kind];
   if (check(yaml.value)) return true;
   const before = problems.lines.length;
   schemaProblems(yaml, check.errors ?? [], problems, describe);

package/runtime/explainer/tutorpage.ts

@@ -27,6 +27,7 @@ import { escape } from "../shared/html.ts";
 import { answerText } from "../shared/questions/render.ts";
 import {
   inLanguage,
+  mapUrl,
   type Block,
   type ComponentExercise,
   type Descriptions,
@@ -72,6 +73,8 @@ interface Words {
   needsIntro: string;
   needs: Readonly<Record<Need, string>>;
   contextTitle: string;
+  /** On a recap page: that it has no exercise, and where the competency is practised ({url}). */
+  recap: string;
   exercise: string;
   steps: string;
   link: string;
@@ -139,6 +142,8 @@ const WORDS: Readonly<Record<string, Words>> = {
         "Zeig Zahlen der Seite als Menge, z. B. „37 sind 3 Zehner und 7 Einer“, aber nie das Ergebnis einer Aufgabe. Ein Schritt pro Nachricht, nie Zeitdruck.",
     },
     contextTitle: "Kontext: die Seite „{page}“",
+    recap:
+      "Diese Seite ist eine Wiederholung: Sie wiederholt etwas, das das Kind schon können sollte, und hat keine Übung. Erklär mit dem Inhalt der Seite und frag nach, ob das Kind ihn verstanden hat. Üben kann es das in anderen Apps; welche das sind, steht hier: {url}",
     exercise: "Übung",
     steps: "Lösungsweg",
     link: "Link",
@@ -205,6 +210,8 @@ const WORDS: Readonly<Record<string, Words>> = {
         "Show numbers of the page as amounts, e.g. “37 is 3 tens and 7 ones”, but never the result of a task. One step per message, never time pressure.",
     },
     contextTitle: "Context: the page “{page}”",
+    recap:
+      "This page is a recap: it goes over something the child should already know, and has no exercise. Explain with the content of the page and ask whether the child has understood it. It can practise it in other apps; which ones, it says here: {url}",
     exercise: "Exercise",
     steps: "Steps of the solution",
     link: "Link",
@@ -341,7 +348,7 @@ export function generatedLines(spec: Generated, site: Site, lang: string, format
   lines.push(`- ${words.linkNumber}: \`${page}?${spec.id}=n&via=tutor#${spec.id}\``);
   const { paths, answer } = placeholdersOf(spec, lang);
   const data = dataOf(spec, site.data);
-  const templates = templatesOf(spec, [lang]);
+  const templates = templatesOf(spec, [lang], data);
   let choices = false;
   const rows = taskSeeds(spec, data).map((seed, index) => {
     const task = generate(spec, seed, data);
@@ -569,6 +576,7 @@ function pageMarkdown(
     `## ${fill(words.contextTitle)}`,
     "",
   );
+  if (page.recap !== undefined) lines.push(words.recap.replace("{url}", mapUrl(page.recap)), "");
   if (page.description !== undefined) lines.push(own(page.description), "");
   lines.push(
     ...contentLines(

package/runtime/shared/blocks/blocks.v1.schema.json

@@ -328,7 +328,7 @@
       "type": "object"
     },
     "latex": {
-      "description": "One formula in the LaTeX subset of the formula command list: \\frac, \\cdot, \\times, \\div, \\%, \\text, ^, _, \\sqrt, \\approx, \\pm, \\le, \\ge, \\neq, \\, (thin space), parentheses and braces; \\ce{…} for chemical equations and \\pu{…} for units (mhchem). Written without the $ signs. A map by language only when it has \\text{…} that differs by language.",
+      "description": "One formula in the LaTeX subset of the formula command list: \\frac, \\cdot, \\times, \\div, \\%, \\text, ^, _, \\sqrt, \\approx, \\pm, \\le, \\ge, \\neq, \\, (thin space), \\  (space), \\quad, \\qquad, \\Rightarrow, \\Leftrightarrow, \\left( … \\right), parentheses and braces; \\sin, \\cos, \\tan, \\arcsin, \\arccos, \\arctan (or \\sin^{-1}), \\circ for degrees (30^\\circ); the Greek letters \\alpha to \\omega (also \\varepsilon, \\vartheta, \\varphi) and the capitals \\Gamma, \\Delta, \\Theta, \\Lambda, \\Xi, \\Pi, \\Sigma, \\Phi, \\Psi, \\Omega; \\ce{…} for chemical equations and \\pu{…} for units (mhchem). The build names any other command and lists these. Written without the $ signs. A map by language only when it has \\text{…} that differs by language.",
       "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
     },
     "table": {

package/runtime/shared/text/formula.ts

@@ -7,6 +7,46 @@ import temml from "temml";
 const mhchem: string = "temml/contrib/mhchem/mhchem.js";
 await import(mhchem);
 
+/** The Greek letters a formula may use, as \\alpha: the small ones, and the capitals that differ from Latin ones. */
+const GREEK = [
+  "alpha",
+  "beta",
+  "gamma",
+  "delta",
+  "varepsilon",
+  "epsilon",
+  "zeta",
+  "eta",
+  "theta",
+  "vartheta",
+  "iota",
+  "kappa",
+  "lambda",
+  "mu",
+  "nu",
+  "xi",
+  "pi",
+  "rho",
+  "sigma",
+  "tau",
+  "upsilon",
+  "varphi",
+  "phi",
+  "chi",
+  "psi",
+  "omega",
+  "Gamma",
+  "Delta",
+  "Theta",
+  "Lambda",
+  "Xi",
+  "Pi",
+  "Sigma",
+  "Phi",
+  "Psi",
+  "Omega",
+];
+
 /** The commands a formula may use (explainer.v1.schema.json, $defs/latex), besides ^, _, braces and parentheses. */
 export const COMMANDS: readonly string[] = [
   "\\frac",
@@ -26,6 +66,25 @@ export const COMMANDS: readonly string[] = [
   "\\}",
   "\\ce",
   "\\pu",
+  // spaces and arrows between the steps of a calculation
+  "\\ ",
+  "\\quad",
+  "\\qquad",
+  "\\Rightarrow",
+  "\\Leftrightarrow",
+  // parentheses that grow with their content
+  "\\left",
+  "\\right",
+  // trigonometry: the functions, their inverses (or \sin^{-1}) and the degree sign (^\circ)
+  "\\sin",
+  "\\cos",
+  "\\tan",
+  "\\arcsin",
+  "\\arccos",
+  "\\arctan",
+  "\\circ",
+  // Greek letters
+  ...GREEK.map((letter) => `\\${letter}`),
 ];
 const allowed = new Set(COMMANDS);
 
@@ -52,7 +111,8 @@ function commands(tex: string): string[] {
 export function formulaProblem(tex: string): string | undefined {
   const unknown = commands(tex).find((command) => !allowed.has(command));
   if (unknown !== undefined) {
-    return `${unknown} is not in the formula command list; write the formula with the commands the schema lists ($defs/latex)`;
+    const list = COMMANDS.map((command) => (command === "\\ " ? "\\  (a space)" : command)).join(", ");
+    return `${unknown} is not in the formula command list; use only these commands, besides ^, _, braces and parentheses: ${list}`;
   }
   try {
     temml.renderToString(tex, { throwOnError: true });

package/scaffold/explainer/src/app.yaml

@@ -1,4 +1,8 @@
-# yaml-language-server: $schema=../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json
+# yaml-language-server: $schema=../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v2.schema.json
+format: 2
+# The strand of the learning map the app stays in, <subject>/<strand> (e.g. mathematik/stochastik); then each page
+# names its competencies. none: the app is on no strand, and no page names competencies.
+strand: none
 title: Platzhalter
 intro: Dieses Kapitel hält den Platz frei, bis der geplante Inhalt da ist.
 languages: [de]

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

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

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

@@ -1,4 +1,4 @@
-# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json
+# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v2.schema.json
 title: Einstieg
 description: Eine Seite, die den Platz frei hält.
 blocks: