@lernapps/app-templates 0.0.0-stage → 0.1.0

package/runtime/interactive/interactive.v1.schema.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:lernapps:schema:interactive.v1",
+  "title": "The start page of a lernapps interactive app",
+  "description": "src/app.yaml of an app built from the archetype interactive (runtime @lernapps/app-templates): what the static start page says, readable without JavaScript, the app's languages and its routes, the modes or levels that each have an address app/#<id>. The build validates it against this schema, then what a schema cannot say (languages complete, restricted Markdown, unique ids), and fails with one line per problem. Every text is for learners, in plain language. A text is a string while German is the app's only language, else a map of texts by language: { de: …, en: … }.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["title", "description", "howto", "competencies", "languages"],
+  "properties": {
+    "title": {
+      "description": "The app's title: the h1 of the start page and of the app page, and the title of both.",
+      "$ref": "#/$defs/text"
+    },
+    "description": {
+      "description": "What the app does and for whom, under the title of the start page.",
+      "$ref": "#/$defs/markdown"
+    },
+    "howto": {
+      "description": "How to play or use the app: the keys, the goal, what counts. The start page shows it under \"So geht's\".",
+      "$ref": "#/$defs/markdown"
+    },
+    "competencies": {
+      "description": "What a learner can do after practising with the app, each an \"Ich kann …\" statement. The start page lists them under \"Das lernst du\".",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/text"
+      }
+    },
+    "languages": {
+      "description": "The languages of the app, German first. Every text is then complete in each of them; each language other than German gets its own pages below /<language>/.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z]{2}$"
+      }
+    },
+    "routes": {
+      "description": "Optional: the modes or levels of the app, each with its address app/#<id>, linked from the start page and listed on the app page. The core starts with the route of the address (start(seed, route)), the first one when the address names none. A topic of the app's catalog entry may link one: app/#<id>.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/route"
+      }
+    },
+    "sections": {
+      "description": "Optional: background sections at the end of the start page, each a heading with its text; its id is its anchor.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/section"
+      }
+    }
+  },
+  "$defs": {
+    "id": {
+      "description": "A stable name, part of the address: lower-case letters, digits and hyphens. Keep it once published, so that links to it keep working.",
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "text": {
+      "description": "A text without formatting: a string while German is the only language of the app, else a map of texts by language ({ de: …, en: … }) with every declared language.",
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": {
+            "pattern": "^[a-z]{2}$"
+          },
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          }
+        }
+      ]
+    },
+    "markdown": {
+      "description": "A text in restricted Markdown (paragraphs, **bold**, *italics*, lists, links, $…$ formulas; no headings, no raw HTML): a string while German is the only language of the app, else a map of texts by language.",
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": {
+            "pattern": "^[a-z]{2}$"
+          },
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          }
+        }
+      ]
+    },
+    "route": {
+      "description": "A mode or level of the app.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title"],
+      "properties": {
+        "id": {
+          "description": "Its anchor: the address app/#<id>.",
+          "$ref": "#/$defs/id"
+        },
+        "title": {
+          "description": "Its name, the text of its links.",
+          "$ref": "#/$defs/text"
+        },
+        "description": {
+          "description": "Optional: what it practises, next to its link on the start page.",
+          "$ref": "#/$defs/text"
+        }
+      }
+    },
+    "section": {
+      "description": "A background section of the start page.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "text"],
+      "properties": {
+        "id": {
+          "description": "Its anchor on the start page: #<id>.",
+          "$ref": "#/$defs/id"
+        },
+        "title": {
+          "description": "Its heading.",
+          "$ref": "#/$defs/text"
+        },
+        "text": {
+          "$ref": "#/$defs/markdown"
+        }
+      }
+    }
+  }
+}

package/runtime/interactive/load.ts

@@ -0,0 +1,188 @@
+// Reads an interactive app's src/app.yaml and its playthroughs (src/playthroughs/*.yaml) at build time and validates
+// them: each file against its schema (interactive.v1.schema.json, playthrough.v1.schema.json), then what a schema
+// cannot say: German first and each declared language complete, restricted Markdown in the texts, unique ids, at
+// least one playthrough, each step doing something (keys or inputs, not both, or ticks) and expecting something, a
+// playthrough's route one of the app's. The YAML helpers are
+// the explainer's (../explainer/load.ts). Each problem is one line: the file, its line, the place in the file, the
+// language where it matters, and what to do.
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { Ajv2020, type ValidateFunction } from "ajv/dist/2020.js";
+import schema from "./interactive.v1.schema.json" with { type: "json" };
+import playthroughSchema from "./playthrough.v1.schema.json" with { type: "json" };
+import { Problems, readYaml, schemaProblems, Texts, type YamlFile } from "../shared/content.ts";
+import { LANGUAGES, languageListProblems, type Text } from "../shared/languages.ts";
+import type { Playthrough } from "./contract.ts";
+
+/** Where an app finds the schemas of its start page and of its playthroughs, for the messages that name them. */
+const SCHEMA_FILE = "node_modules/@lernapps/app-templates/runtime/interactive/interactive.v1.schema.json";
+const PLAYTHROUGH_SCHEMA_FILE = "node_modules/@lernapps/app-templates/runtime/interactive/playthrough.v1.schema.json";
+export const RULE_URL = "https://lernapps.net/tooling/rules/#interactive-app-valid";
+export const APP = "src/app.yaml";
+export const PLAYTHROUGHS = "src/playthroughs";
+
+export interface Route {
+  id: string;
+  title: Text;
+  description?: Text;
+}
+
+export interface Section {
+  id: string;
+  title: Text;
+  text: Text;
+}
+
+/** src/app.yaml: what the start page says, the languages and the routes. */
+export interface App {
+  title: Text;
+  description: Text;
+  howto: Text;
+  competencies: readonly Text[];
+  languages: readonly string[];
+  routes?: readonly Route[];
+  sections?: readonly Section[];
+}
+
+/** A playthrough with its file, for the lines of its problems. */
+export interface PlaythroughFile {
+  yaml: YamlFile;
+  playthrough: Playthrough;
+}
+
+export interface Interactive {
+  app: App;
+  appYaml: YamlFile;
+  playthroughs: readonly PlaythroughFile[];
+}
+
+/** The app is not valid: one problem per line in `problems`. */
+export class InteractiveError extends Error {
+  readonly problems: readonly string[];
+  constructor(problems: readonly string[]) {
+    super(
+      [
+        `the interactive app in src/ is not valid (${RULE_URL}):`,
+        ...problems.map((problem) => `  - ${problem}`),
+        `Fix it as the schemas say: ${SCHEMA_FILE}, ${PLAYTHROUGH_SCHEMA_FILE}`,
+      ].join("\n"),
+    );
+    this.problems = problems;
+  }
+}
+
+const ajv = new Ajv2020({ allErrors: true, strict: true, allowUnionTypes: true });
+const validators: Record<"app" | "playthrough", ValidateFunction> = {
+  app: ajv.compile(schema),
+  playthrough: ajv.compile(playthroughSchema),
+};
+
+function validate(yaml: YamlFile, kind: keyof typeof validators, problems: Problems): boolean {
+  const check = validators[kind];
+  if (check(yaml.value)) return true;
+  const before = problems.lines.length;
+  schemaProblems(yaml, check.errors ?? [], problems);
+  if (problems.lines.length === before) problems.at(yaml, [], "does not match the schema");
+  return false;
+}
+
+/** The problems of a list of ids: each once. */
+function uniqueIds(yaml: YamlFile, key: string, items: readonly { id: string }[], problems: Problems): void {
+  items.forEach((item, index) => {
+    if (items.findIndex((other) => other.id === item.id) !== index) {
+      problems.at(yaml, [key, index, "id"], `${item.id} is used twice in ${key}; give each its own id`);
+    }
+  });
+}
+
+/** The app in `root`, or the problems that keep it from building. */
+export function check(root: string): { interactive?: Interactive; problems: string[] } {
+  const problems = new Problems();
+  if (!existsSync(join(root, APP))) {
+    problems.add(`${APP} is missing: the start page of the app comes from it (${SCHEMA_FILE})`);
+    return { problems: problems.lines };
+  }
+  const appYaml = readYaml(root, APP, problems);
+  if (appYaml === undefined || !validate(appYaml, "app", problems)) return { problems: problems.lines };
+  const app = appYaml.value as App;
+  const languageList = languageListProblems(app.languages, LANGUAGES);
+  for (const problem of languageList) {
+    problems.at(appYaml, ["languages", Math.max(app.languages.lastIndexOf(problem.lang), 0)], problem.message);
+  }
+  if (languageList.length > 0) return { problems: problems.lines };
+  const texts = new Texts(app.languages, problems);
+  texts.check(appYaml, ["title"], "plain");
+  texts.check(appYaml, ["description"], "markdown");
+  texts.check(appYaml, ["howto"], "markdown");
+  app.competencies.forEach((_, index) => texts.check(appYaml, ["competencies", index], "plain"));
+  (app.routes ?? []).forEach((_, index) => {
+    texts.check(appYaml, ["routes", index, "title"], "plain");
+    texts.check(appYaml, ["routes", index, "description"], "plain");
+  });
+  (app.sections ?? []).forEach((_, index) => {
+    texts.check(appYaml, ["sections", index, "title"], "plain");
+    texts.check(appYaml, ["sections", index, "text"], "markdown");
+  });
+  uniqueIds(appYaml, "routes", app.routes ?? [], problems);
+  uniqueIds(appYaml, "sections", app.sections ?? [], problems);
+  // the playthroughs only of a valid app.yaml: they refer to its routes
+  if (problems.lines.length > 0) return { problems: problems.lines };
+
+  const routes = (app.routes ?? []).map((route) => route.id);
+  const files = existsSync(join(root, PLAYTHROUGHS))
+    ? readdirSync(join(root, PLAYTHROUGHS))
+        .filter((file) => file.endsWith(".yaml"))
+        .sort()
+    : [];
+  if (files.length === 0) {
+    problems.add(
+      `${PLAYTHROUGHS}/: no playthrough; write at least one, <name>.yaml: a seed, and steps of keys, inputs or ticks with the state or announcement expected after them (${PLAYTHROUGH_SCHEMA_FILE})`,
+    );
+  }
+  const playthroughs: PlaythroughFile[] = [];
+  for (const file of files) {
+    const yaml = readYaml(root, `${PLAYTHROUGHS}/${file}`, problems);
+    if (yaml === undefined || !validate(yaml, "playthrough", problems)) continue;
+    const playthrough = yaml.value as Playthrough;
+    if (playthrough.route !== undefined && !routes.includes(playthrough.route)) {
+      problems.at(
+        yaml,
+        ["route"],
+        routes.length === 0
+          ? `${playthrough.route}: ${APP} has no routes; leave route out`
+          : `${playthrough.route} is not a route of ${APP}; use one of ${routes.join(", ")}`,
+      );
+    }
+    playthrough.steps.forEach((step, index) => {
+      if (step.keys !== undefined && step.inputs !== undefined) {
+        problems.at(
+          yaml,
+          ["steps", index, "inputs"],
+          "keys and inputs in one step; write the keys as key inputs ({ kind: key, key: a }) in inputs, or give each its own step",
+        );
+      } else if (step.keys === undefined && step.inputs === undefined && step.ticks === undefined) {
+        problems.at(
+          yaml,
+          ["steps", index],
+          "does nothing; give the keys (keys) or inputs (inputs) of the step, the ticks that pass (ticks), or both",
+        );
+      } else if (step.state === undefined && step.announce === undefined) {
+        problems.at(
+          yaml,
+          ["steps", index],
+          "expects nothing; give the state expected after the step (state), the announcement (announce), or both",
+        );
+      }
+    });
+    playthroughs.push({ yaml, playthrough });
+  }
+  if (problems.lines.length > 0) return { problems: problems.lines };
+  return { interactive: { app, appYaml, playthroughs }, problems: [] };
+}
+
+/** The app in `root`; an InteractiveError with every problem when it is not valid. */
+export function loadInteractive(root: string): Interactive {
+  const { interactive, problems } = check(root);
+  if (interactive === undefined) throw new InteractiveError(problems);
+  return interactive;
+}

package/runtime/interactive/messages/de.json

@@ -0,0 +1,14 @@
+{
+  "language": "Deutsch",
+  "languages": "Sprache",
+  "play": "Los geht's",
+  "routes": "Auswahl",
+  "howto": "So geht's",
+  "competencies": "Das lernst du",
+  "noscript": "Für die App brauchst du JavaScript. Schalte es in deinem Browser ein. Alles andere auf dieser Seite kannst du auch ohne lesen.",
+  "noscriptApp": "Diese App braucht JavaScript. Schalte es in deinem Browser ein. Was die App macht, steht auf der Startseite.",
+  "toStart": "Zur Startseite",
+  "footer": "Eine interaktive App auf lernapps.net",
+  "imprint": "Impressum",
+  "privacy": "Datenschutz"
+}

package/runtime/interactive/messages/en.json

@@ -0,0 +1,14 @@
+{
+  "language": "English",
+  "languages": "Language",
+  "play": "Let's go",
+  "routes": "Choose",
+  "howto": "How it works",
+  "competencies": "What you learn",
+  "noscript": "The app needs JavaScript. Turn it on in your browser. You can read everything else on this page without it.",
+  "noscriptApp": "This app needs JavaScript. Turn it on in your browser. The start page says what the app does.",
+  "toStart": "To the start page",
+  "footer": "An interactive app on lernapps.net",
+  "imprint": "Imprint",
+  "privacy": "Privacy"
+}

package/runtime/interactive/messages.ts

@@ -0,0 +1,11 @@
+// The interactive shell's own texts for learners, in each language it has them: an app may declare only these
+// languages.
+import de from "./messages/de.json" with { type: "json" };
+import en from "./messages/en.json" with { type: "json" };
+import { textsIn, type Language } from "../shared/languages.ts";
+
+export type Messages = typeof de;
+export const MESSAGES: Readonly<Record<Language, Messages>> = { de, en };
+
+/** The text of `key` in `lang`. */
+export const message = (lang: string, key: keyof Messages): string => textsIn(MESSAGES, lang)[key];

package/runtime/interactive/playthrough.v1.schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:lernapps:schema:playthrough.v1",
+  "title": "A playthrough of a lernapps interactive app",
+  "description": "A file src/playthroughs/<name>.yaml of an app built from the archetype interactive: what a learner does, from the start of a route with a seed: inputs (keys typed, actions of the app's root component) and time passing (ticks), and after each step what is expected: the state of the core (the fields named, compared with the state step(state, input) and tick(state, dt) give) or the announcement for screen readers (@lernapps/tooling/a11y), or both. The build plays every playthrough against the core and fails with one line per mismatch; the end-to-end tests play the same inputs and ticks in the browser. In both, no time passes but the ticks a step names.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["seed", "steps"],
+  "properties": {
+    "route": {
+      "description": "The route it starts at, an id of routes in src/app.yaml; the first route when it names none.",
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "seed": {
+      "description": "The seed it starts with: start(seed, route); in the browser the address app/?seed=<seed>#<route>.",
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2147483647
+    },
+    "steps": {
+      "description": "The steps, in order.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/step"
+      }
+    }
+  },
+  "$defs": {
+    "step": {
+      "description": "What happens: keys or inputs, then ticks, at least one of them; then what is expected after them: state, announce, or both.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "keys": {
+          "description": "Keys, one after the other, each as the browser names it (KeyboardEvent.key): a, A, Enter, \" \" for the space bar, ArrowLeft. The short form of inputs that are all keys; a step has keys or inputs, not both.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "inputs": {
+          "description": "Inputs, one after the other: a key ({ kind: key, key: a }), pressed on the keyboard in the browser, or an action of the app's root component ({ kind: action, name: again }, with a value if it has one), emitted by the root component as input in the browser.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/input"
+          }
+        },
+        "ticks": {
+          "description": "The ticks that pass after the keys or inputs: tick(state, TICK) that many times, TICK = 20 ms, so 50 ticks are a second.",
+          "type": "integer",
+          "minimum": 1
+        },
+        "state": {
+          "description": "The state expected after the step: the fields named, each compared in the same way; a list or any other value is compared as a whole."
+        },
+        "announce": {
+          "description": "The announcement expected after the step, in German: what @lernapps/tooling/a11y's announce said last. Only the browser can see it.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      }
+    },
+    "input": {
+      "description": "An input to the core: step(state, input). Told apart by kind.",
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "enum": ["key", "action"]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "key"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/$defs/key"
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "action"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/$defs/action"
+          }
+        }
+      ]
+    },
+    "key": {
+      "description": "A key, as the browser names it (KeyboardEvent.key).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "key"],
+      "properties": {
+        "kind": {
+          "const": "key"
+        },
+        "key": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "action": {
+      "description": "An action the app's root component emits as input, for what the learner does with the pointer or by touch.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "name"],
+      "properties": {
+        "kind": {
+          "const": "action"
+        },
+        "name": {
+          "description": "The name the app gives the action.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "value": {
+          "description": "The JSON value the action carries, if it needs one."
+        }
+      }
+    }
+  }
+}