@lernapps/app-templates 0.2.1 → 0.3.1

package/runtime/explainer/explainer.v2.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:lernapps:schema:explainer.v2",
+  "title": "Content of a lernapps explainer, format 2",
+  "description": "Format 2 of an explainer's content, as YAML in src/: src/app.yaml, src/<chapter>/chapter.yaml, src/<chapter>/<page>.yaml and src/data/<name>.yaml. It is format 1 (explainer.v1.schema.json) plus the app's place on the learning map: format: 2 and strand in src/app.yaml, and on each page the competencies it practises, or recap on a page that repeats a competency from elsewhere. An app.yaml without format is format 1.",
+  "allOf": [
+    {
+      "if": {
+        "type": "object",
+        "required": ["chapters"],
+        "properties": {
+          "chapters": {}
+        }
+      },
+      "then": {
+        "$ref": "#/$defs/app"
+      }
+    },
+    {
+      "if": {
+        "type": "object",
+        "required": ["pages"],
+        "properties": {
+          "pages": {}
+        }
+      },
+      "then": {
+        "$ref": "#/$defs/chapter"
+      }
+    },
+    {
+      "if": {
+        "type": "object",
+        "required": ["blocks"],
+        "properties": {
+          "blocks": {}
+        }
+      },
+      "then": {
+        "$ref": "#/$defs/page"
+      }
+    },
+    {
+      "if": {
+        "type": "array"
+      },
+      "then": {
+        "$ref": "#/$defs/data"
+      }
+    }
+  ],
+  "$defs": {
+    "id": {
+      "$ref": "urn:lernapps:schema:explainer.v1#/$defs/id"
+    },
+    "strand": {
+      "description": "The one strand (Strang) of the learning map the app belongs to, <subject>/<strand>, e.g. mathematik/stochastik; or none if it belongs to none (then it is not on the map).",
+      "type": "string",
+      "pattern": "^(none|[a-z0-9]+(-[a-z0-9]+)*/[a-z0-9]+(-[a-z0-9]+)*)$"
+    },
+    "competency": {
+      "description": "A competency of the learning map, <subject>/<competency>, e.g. physik/gewichtskraft-berechnen.",
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*/[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "app": {
+      "description": "src/app.yaml in format 2: format: 2 and strand, everything else as in format 1.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["format", "strand", "title", "intro", "languages", "chapters"],
+      "properties": {
+        "format": {
+          "description": "Always 2. Without it, the content is format 1 (explainer.v1.schema.json).",
+          "const": 2
+        },
+        "strand": {
+          "$ref": "#/$defs/strand"
+        },
+        "title": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/title"
+        },
+        "intro": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/intro"
+        },
+        "languages": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/languages"
+        },
+        "chapters": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/chapters"
+        },
+        "sources": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/sources"
+        },
+        "tutor": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/tutor"
+        },
+        "scope": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/scope"
+        }
+      }
+    },
+    "chapter": {
+      "$ref": "urn:lernapps:schema:explainer.v1#/$defs/chapter"
+    },
+    "page": {
+      "description": "src/<chapter>/<page>.yaml in format 2: a page as in format 1, plus competencies, or recap on a recap page.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title", "blocks"],
+      "properties": {
+        "title": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/page/properties/title"
+        },
+        "description": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/page/properties/description"
+        },
+        "competencies": {
+          "description": "The competencies (Bausteine) the page practises, ids of the subject of the app's strand; as a rule one. Required when the app has a strand; leave it out with strand: none and on a recap page. The catalog checks the ids when it lists the app.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/id"
+          }
+        },
+        "recap": {
+          "description": "Makes the page a recap page: it repeats a competency that the app's competencies require but the app does not practise, e.g. physik/gewichtskraft-berechnen. Use it instead of competencies, also with strand: none. A recap page has descriptive blocks only, no exercise; the link to the competency on the learning map is added for you.",
+          "$ref": "#/$defs/competency"
+        },
+        "blocks": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/page/properties/blocks"
+        },
+        "scope": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/page/properties/scope"
+        }
+      },
+      "not": {
+        "required": ["competencies", "recap"],
+        "properties": {
+          "competencies": {},
+          "recap": {}
+        }
+      }
+    },
+    "data": {
+      "$ref": "urn:lernapps:schema:explainer.v1#/$defs/data"
+    },
+    "event": {
+      "$ref": "urn:lernapps:schema:explainer.v1#/$defs/event"
+    }
+  }
+}

package/runtime/explainer/expression.ts

@@ -4,7 +4,10 @@
 // - arithmetic on exact fractions: + - * /, parentheses, unary minus; numbers as written (0.1 is 1/10);
 // - comparisons == != < <= > >=, and, or, not; true, false; strings in quotes;
 // - record fields (e.year), list index (xs[0]), list literals ([1, 2, 3]);
-// - the functions round(x, n), decimals(x), map(xs, field), sortBy(xs, field), reverse(xs).
+// - the functions round(x, n), decimals(x), map(xs, field), sortBy(xs, field), reverse(xs);
+// - the functions sqrt(x), pow(x, n), sin(x), cos(x), tan(x) and asin(x), acos(x), atan(x), with angles in degrees as
+//   in school (sin(30) is 1/2). A result is exact where it is rational (sqrt(9/4), pow(2, 10), sin(30), cos(60),
+//   tan(45), asin(1/2)); otherwise it is the value to 12 decimal places, which an exercise rounds with round(x, n).
 // Errors are ExpressionErrors whose message says what to change.
 import { Fraction } from "./fraction.ts";
 
@@ -49,6 +52,14 @@ const FUNCTIONS: Readonly<Record<string, { arity: number; field?: number }>> = {
   map: { arity: 2, field: 1 },
   sortBy: { arity: 2, field: 1 },
   reverse: { arity: 1 },
+  sqrt: { arity: 1 },
+  pow: { arity: 2 },
+  sin: { arity: 1 },
+  cos: { arity: 1 },
+  tan: { arity: 1 },
+  asin: { arity: 1 },
+  acos: { arity: 1 },
+  atan: { arity: 1 },
 };
 const KEYWORDS = new Set(["and", "or", "not", "true", "false"]);
 
@@ -322,6 +333,107 @@ function integer(value: Fraction, what: string): number {
   return Number(value.n);
 }
 
+/** The decimal places of a result that is not rational (sqrt(2), sin(10)): enough for any rounding of an exercise. */
+export const APPROXIMATION_PLACES = 12;
+
+/** A real number that is no fraction, as the fraction of its first APPROXIMATION_PLACES decimals. */
+function approximate(value: number, what: string): Fraction {
+  if (!Number.isFinite(value)) throw new ExpressionError(`${what} has no result here`);
+  return Fraction.from(Number(value.toFixed(APPROXIMATION_PLACES)));
+}
+
+/** The square root of a whole number ≥ 0, if it is whole. */
+function wholeRoot(n: bigint): bigint | undefined {
+  if (n < 2n) return n;
+  let x = BigInt(Math.floor(Math.sqrt(Number(n))));
+  while (x * x > n) x--;
+  while ((x + 1n) * (x + 1n) <= n) x++;
+  return x * x === n ? x : undefined;
+}
+
+function sqrt(x: Fraction): Fraction {
+  if (x.n < 0n) throw new ExpressionError(`sqrt needs a number ≥ 0, not ${x.toNumber()}`);
+  const n = wholeRoot(x.n);
+  const d = wholeRoot(x.d);
+  return n !== undefined && d !== undefined ? Fraction.of(n, d) : approximate(Math.sqrt(x.toNumber()), "sqrt");
+}
+
+/** The largest exponent of pow: beyond it, a number has more digits than any exercise shows. */
+const MAX_EXPONENT = 1000;
+
+function pow(x: Fraction, n: Fraction): Fraction {
+  if (n.isInteger()) {
+    const e = Number(n.n);
+    if (Math.abs(e) > MAX_EXPONENT)
+      throw new ExpressionError(`pow takes an exponent from -${MAX_EXPONENT} to ${MAX_EXPONENT}`);
+    if (x.n === 0n && e < 0) throw new ExpressionError("pow(0, n) needs n ≥ 0: division by zero");
+    const power = Fraction.of(x.n ** BigInt(Math.abs(e)), x.d ** BigInt(Math.abs(e)));
+    return e < 0 ? Fraction.of(1).div(power) : power;
+  }
+  if (x.n < 0n) throw new ExpressionError("pow of a negative number needs a whole exponent");
+  return approximate(x.toNumber() ** n.toNumber(), "pow");
+}
+
+/** The angle `x` in degrees, brought into 0 ≤ x < 360 exactly. */
+function turn(x: Fraction): Fraction {
+  const full = Fraction.of(360);
+  const quotient = x.div(full);
+  // floor of the quotient
+  let floor = quotient.n / quotient.d;
+  if (quotient.n < 0n && quotient.n % quotient.d !== 0n) floor -= 1n;
+  return x.sub(full.mul(Fraction.of(floor)));
+}
+
+/** The sine of the angles 0°, 30°, 90°, … whose sine is rational, in degrees. */
+const EXACT_SINE: ReadonlyMap<number, Fraction> = new Map([
+  [0, Fraction.of(0)],
+  [30, Fraction.of(1, 2)],
+  [90, Fraction.of(1)],
+  [150, Fraction.of(1, 2)],
+  [180, Fraction.of(0)],
+  [210, Fraction.of(-1, 2)],
+  [270, Fraction.of(-1)],
+  [330, Fraction.of(-1, 2)],
+]);
+const RADIANS = Math.PI / 180;
+
+function sine(degrees: Fraction): Fraction {
+  const angle = turn(degrees);
+  const exact = angle.isInteger() ? EXACT_SINE.get(Number(angle.n)) : undefined;
+  return exact ?? approximate(Math.sin(angle.toNumber() * RADIANS), "sin");
+}
+
+const cosine = (degrees: Fraction): Fraction => sine(degrees.add(Fraction.of(90)));
+
+function tangent(degrees: Fraction): Fraction {
+  const angle = turn(degrees);
+  const cos = cosine(angle);
+  if (cos.n === 0n) throw new ExpressionError(`tan(${degrees.toNumber()}) has no value: the cosine of the angle is 0`);
+  if (angle.isInteger() && [45, 135, 225, 315].includes(Number(angle.n))) {
+    return Fraction.of(Number(angle.n) % 180 === 45 ? 1 : -1);
+  }
+  const sin = sine(angle);
+  return sin.n === 0n ? sin : approximate(Math.tan(angle.toNumber() * RADIANS), "tan");
+}
+
+/** The inverse of sin, cos or tan in degrees: exact for the values of the angles of EXACT_SINE and of 45°. */
+function inverse(fn: "asin" | "acos" | "atan", x: Fraction): Fraction {
+  if (fn !== "atan" && (x.compare(Fraction.of(-1)) < 0 || x.compare(Fraction.of(1)) > 0)) {
+    throw new ExpressionError(`${fn} needs a number from -1 to 1, not ${x.toNumber()}`);
+  }
+  const exact: Readonly<Record<string, number>> =
+    fn === "asin"
+      ? { "-1": -90, "-1/2": -30, "0": 0, "1/2": 30, "1": 90 }
+      : fn === "acos"
+        ? { "-1": 180, "-1/2": 120, "0": 90, "1/2": 60, "1": 0 }
+        : { "-1": -45, "0": 0, "1": 45 };
+  const known = exact[x.toString()];
+  if (known !== undefined) return Fraction.of(known);
+  const radians =
+    fn === "asin" ? Math.asin(x.toNumber()) : fn === "acos" ? Math.acos(x.toNumber()) : Math.atan(x.toNumber());
+  return approximate(radians / RADIANS, fn);
+}
+
 function call(fn: string, args: readonly Node[], env: Readonly<Record<string, Value>>): Value {
   const value = (index: number) => evaluate(args[index] as Node, env);
   const field = () => (args[1] as Extract<Node, { kind: "name" }>).name;
@@ -341,6 +453,20 @@ function call(fn: string, args: readonly Node[], env: Readonly<Record<string, Va
     }
     case "reverse":
       return [...asList(value(0), "reverse")].reverse();
+    case "sqrt":
+      return sqrt(asNumber(value(0), "sqrt"));
+    case "pow":
+      return pow(asNumber(value(0), "pow"), asNumber(value(1), "pow"));
+    case "sin":
+      return sine(asNumber(value(0), "sin"));
+    case "cos":
+      return cosine(asNumber(value(0), "cos"));
+    case "tan":
+      return tangent(asNumber(value(0), "tan"));
+    case "asin":
+    case "acos":
+    case "atan":
+      return inverse(fn, asNumber(value(0), fn));
     default:
       throw new ExpressionError(`${fn} is not a function of the expression language`);
   }

package/runtime/explainer/generated/texts.ts

@@ -18,6 +18,10 @@ const PATH_ONLY = new RegExp(String.raw`^${PATH}$`);
 const SPACED = new RegExp(String.raw`\{\{\s*(${PATH})\s*\}\}`, "g");
 /** A formula ($…$) or a run of prose, in a template. */
 const SEGMENT = /\$((?:\\.|[^\\$\n])+?)\$|([^$]+)/g;
+/** A chemical formula whose whole argument is one placeholder: \ce{{{e.gl}}}. */
+const CHEM = new RegExp(String.raw`\\ce\{\{\{(${PATH})\}\}\}`, "g");
+/** The start of the token of a placeholder that is the whole argument of \ce: ⟦ce:e.gl⟧. */
+const CHEM_TOKEN = "ce:";
 
 const formats = new Map<string, Intl.NumberFormat>();
 /** A number as the page shows it: up to six decimals, no grouping (a learner would type 1500, not 1.500). */
@@ -54,15 +58,89 @@ export function answerLabel(spec: Generated, task: Task, lang: string): string {
   return label(task.answer, lang);
 }
 
-/** A template's placeholders as tokens: {{G}} becomes ⟦G⟧, inside a formula ($…$) {\text{⟦G⟧}}. */
+/**
+ * A template's placeholders as tokens: {{G}} becomes ⟦G⟧, inside a formula ($…$) {\text{⟦G⟧}}; a chemical formula
+ * whose whole argument is a placeholder, \ce{{{e.gl}}}, becomes {\text{⟦ce:e.gl⟧}}, which fill() replaces by the
+ * formula the build set for the task's value (LanguageTemplates.chem).
+ */
 export function tokenize(text: string): string {
   return text.replace(SEGMENT, (whole, math: string | undefined, prose: string | undefined) =>
     math !== undefined
-      ? `$${math.replace(PLACEHOLDER, (_placeholder, path: string) => `{\\text{⟦${path}⟧}}`)}$`
+      ? `$${math
+          .replace(CHEM, (_chem, path: string) => `{\\text{⟦${CHEM_TOKEN}${path}⟧}}`)
+          .replace(PLACEHOLDER, (_placeholder, path: string) => `{\\text{⟦${path}⟧}}`)}$`
       : (prose ?? whole).replace(PLACEHOLDER, (_placeholder, path: string) => `⟦${path}⟧`),
   );
 }
 
+/** The formulas of a template ($…$), as written. */
+const formulasIn = (text: string): string[] =>
+  [...text.matchAll(SEGMENT)].flatMap((match) => (match[1] === undefined ? [] : [match[1]]));
+
+/** The placeholders that are the whole argument of a \ce in a formula of a template (\ce{{{e.gl}}}), by their path. */
+export function chemPlaceholdersIn(text: string): string[] {
+  return formulasIn(text).flatMap((math) => [...math.matchAll(CHEM)].map((match) => match[1] ?? ""));
+}
+
+/** The argument of each \ce and \pu of a formula, with its command; braces balanced. */
+function mhchemArguments(math: string): { command: string; argument: string }[] {
+  const found: { command: string; argument: string }[] = [];
+  for (const match of math.matchAll(/\\(ce|pu)\s*\{/g)) {
+    const start = (match.index ?? 0) + match[0].length;
+    let depth = 1;
+    for (let at = start; at < math.length; at++) {
+      if (math[at] === "{") depth++;
+      else if (math[at] === "}" && --depth === 0) {
+        found.push({ command: `\\${match[1] ?? ""}`, argument: math.slice(start, at) });
+        break;
+      }
+    }
+  }
+  return found;
+}
+
+const WHOLE_PLACEHOLDER = new RegExp(String.raw`^\{\{${PATH}\}\}$`);
+
+/**
+ * The problems of the placeholders in \ce and \pu of one template. A placeholder in \ce is its whole argument,
+ * \ce{{{e.gl}}}, drawn from a finite list (oneOf, or pick: 1 from a list or a data file), so that the build can set
+ * the formula of every value; \pu takes none.
+ */
+export function chemProblems(text: string, given: Generated["given"]): string[] {
+  const problems: string[] = [];
+  for (const math of formulasIn(text)) {
+    for (const { command, argument } of mhchemArguments(math)) {
+      if (placeholdersIn(argument).length === 0) continue;
+      if (command === "\\pu") {
+        problems.push(
+          `\\pu{${argument}} has a placeholder inside; \\pu takes none: write the number before it, e.g. {{m}}\\,\\pu{g}`,
+        );
+      } else if (!WHOLE_PLACEHOLDER.test(argument)) {
+        problems.push(
+          `\\ce{${argument}} has a placeholder among other text; in \\ce a placeholder is the whole argument, \\ce{{{e.gl}}}: put the whole formula into one field of the data (gl: "2H2 + O2 -> 2H2O")`,
+        );
+      }
+    }
+  }
+  for (const path of chemPlaceholdersIn(text)) {
+    const root = path.split(".")[0] ?? "";
+    if (root === "answer") {
+      problems.push(
+        "\\ce{{{answer}}} is not possible: the build sets only the formulas of values drawn from a list; show the formula of a value of given",
+      );
+      continue;
+    }
+    const arbitrary = given[root];
+    if (arbitrary === undefined) continue; // reported as an unknown placeholder
+    if (arbitrary.oneOf === undefined && !(arbitrary.from !== undefined && arbitrary.pick === 1)) {
+      problems.push(
+        `\\ce{{{${path}}}} needs one value from a list: draw ${root} with oneOf, or with pick: 1 from a list or a data file, so that the build can set the formula of each value`,
+      );
+    }
+  }
+  return problems;
+}
+
 /** The placeholders of a template, by their path (G, e.name, answer). */
 export function placeholdersIn(text: string): string[] {
   return [...text.matchAll(PLACEHOLDER)].map((match) => match[1] ?? "");
@@ -136,7 +214,7 @@ export function templateProblems(spec: Generated): { path: (string | number)[];
   const declared = [...Object.keys(spec.given), "answer"];
   return writtenTemplates(spec).flatMap(({ path, lang, text }) => {
     const known = new Set(declared);
-    return placeholderProblems(text, known).map((message) => ({
+    return [...placeholderProblems(text, known), ...chemProblems(text, spec.given)].map((message) => ({
       path,
       ...(lang === undefined ? {} : { lang }),
       message,
@@ -194,10 +272,18 @@ export function fill(
   task: Task,
   lang: string,
   mode: "html" | "text" = "html",
+  chem: Readonly<Record<string, string>> = {},
 ): string {
   const withMath =
     mode === "html"
-      ? template.replace(/<mtext>⟦([^⟧]+)⟧<\/mtext>/g, (_whole, path: string) => {
+      ? template.replace(/<mtext>⟦([^⟧]+)⟧<\/mtext>/g, (_whole, token: string) => {
+          if (token.startsWith(CHEM_TOKEN)) {
+            const path = token.slice(CHEM_TOKEN.length);
+            const value = placeholderValue(spec, task, path, lang);
+            if (value === undefined) return `<mtext>{{${escape(path)}}}</mtext>`;
+            return chem[value.text] ?? `<mtext>${escape(value.text)}</mtext>`;
+          }
+          const path = token;
           const value = placeholderValue(spec, task, path, lang);
           if (value === undefined) return `<mtext>{{${escape(path)}}}</mtext>`;
           if (value.number === undefined) return `<mtext>${escape(value.text)}</mtext>`;
@@ -206,7 +292,8 @@ export function fill(
           return negative ? `<mo>−</mo><mn>${digits}</mn>` : `<mn>${digits}</mn>`;
         })
       : template;
-  return withMath.replace(/⟦([^⟧]+)⟧/g, (_whole, path: string) => {
+  return withMath.replace(/⟦([^⟧]+)⟧/g, (_whole, token: string) => {
+    const path = token.startsWith(CHEM_TOKEN) ? token.slice(CHEM_TOKEN.length) : token;
     const value = placeholderValue(spec, task, path, lang);
     if (value === undefined) return `{{${path}}}`;
     return mode === "html" ? escape(value.text) : value.text;
@@ -229,18 +316,20 @@ export const templatesIn = (templates: Templates, lang: string): LanguageTemplat
 
 /** The task's text as HTML, in `lang`. */
 export function taskText(spec: Generated, task: Task, lang: string, templates: Templates): string {
-  return fill(templatesIn(templates, lang).task, spec, task, lang);
+  const { task: text, chem } = templatesIn(templates, lang);
+  return fill(text, spec, task, lang, "html", chem);
 }
 
 /** The steps of the solution as HTML, in `lang`. */
 export function stepsOf(spec: Generated, task: Task, lang: string, templates: Templates): string[] {
-  return templatesIn(templates, lang).steps.map((step) => fill(step, spec, task, lang));
+  const { steps, chem } = templatesIn(templates, lang);
+  return steps.map((step) => fill(step, spec, task, lang, "html", chem));
 }
 
 /** The hint as HTML, in `lang`, if the exercise has one. */
 export function hintOf(spec: Generated, task: Task, lang: string, templates: Templates): string | undefined {
-  const hint = templatesIn(templates, lang).hint;
-  return hint === undefined ? undefined : fill(hint, spec, task, lang);
+  const { hint, chem } = templatesIn(templates, lang);
+  return hint === undefined ? undefined : fill(hint, spec, task, lang, "html", chem);
 }
 
 /** The text of HTML, as a learner reads it: tags left out, entities resolved, white space folded. */

package/runtime/explainer/generated/types.ts

@@ -17,6 +17,9 @@
 // around a lone name ({{G}}), means the same as the letter alone, so nothing is lost; any other group ({{G}^2},
 // {{G} + 1}) stays a group. To fill in a value where the formula needs a group, keep the group: \frac{{{W}}}{{{G}}}.
 // Two braces with spaces inside ({{ G }}) are an error everywhere, as they were most likely meant as a placeholder.
+// In \ce a placeholder is the whole argument, \ce{{{e.gl}}}, drawn from a finite list (oneOf, or pick: 1 from a list
+// or a data file): the build sets the formula of each value with mhchem (LanguageTemplates.chem), and fill() puts in
+// the one of the task's value. A placeholder among other text in \ce, or any in \pu, is an error.
 
 // This module: the types of a generated exercise, its task and its data.
 import { type Value } from "../expression.ts";
@@ -90,6 +93,11 @@ export interface LanguageTemplates {
   hint?: string | undefined;
   /** The mistakes' messages, plain text. */
   messages: string[];
+  /**
+   * The chemical formula of each value of the placeholders in \ce{{{…}}}, as MathML without <math>, by the value as
+   * the learner reads it; fill() puts it in for the token ⟦ce:…⟧.
+   */
+  chem?: Readonly<Record<string, string>>;
 }
 export type Templates = Readonly<Record<string, LanguageTemplates>>;