@lernapps/app-templates 0.0.1 → 0.1.1

package/runtime/shared/text/formula.ts

@@ -0,0 +1,69 @@
+// Formulas at build time: the LaTeX subset of the formula command list, checked, then rendered by Temml to MathML,
+// which current browsers show and screen readers read without a script or a font. \ce{…} and \pu{…} come from
+// Temml's mhchem extension, which registers itself on a global temml; it is loaded once, here.
+import temml from "temml";
+
+(globalThis as { temml?: typeof temml }).temml = temml;
+const mhchem: string = "temml/contrib/mhchem/mhchem.js";
+await import(mhchem);
+
+/** The commands a formula may use (explainer.v1.schema.json, $defs/latex), besides ^, _, braces and parentheses. */
+export const COMMANDS: readonly string[] = [
+  "\\frac",
+  "\\cdot",
+  "\\times",
+  "\\div",
+  "\\%",
+  "\\text",
+  "\\sqrt",
+  "\\approx",
+  "\\pm",
+  "\\le",
+  "\\ge",
+  "\\neq",
+  "\\,",
+  "\\{",
+  "\\}",
+  "\\ce",
+  "\\pu",
+];
+const allowed = new Set(COMMANDS);
+
+/** The commands of `tex` outside the arguments of \ce and \pu, which mhchem reads in its own notation. */
+function commands(tex: string): string[] {
+  const found: string[] = [];
+  for (let at = 0; at < tex.length; at++) {
+    if (tex[at] !== "\\") continue;
+    const word = /^\\(?:[a-zA-Z]+|.)/.exec(tex.slice(at))?.[0] ?? "\\";
+    found.push(word);
+    at += word.length - 1;
+    if ((word === "\\ce" || word === "\\pu") && tex[at + 1] === "{") {
+      let depth = 0;
+      for (at++; at < tex.length; at++) {
+        if (tex[at] === "{") depth++;
+        else if (tex[at] === "}" && --depth === 0) break;
+      }
+    }
+  }
+  return found;
+}
+
+/** What is wrong with the formula `tex`, or undefined when it is in the command list and parses. */
+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)`;
+  }
+  try {
+    temml.renderToString(tex, { throwOnError: true });
+    return undefined;
+  } catch (error) {
+    const message = (error instanceof Error ? error.message : String(error)).split("\n")[0]?.trim() ?? "";
+    return `the formula does not parse: ${message}`;
+  }
+}
+
+/** The formula as MathML: a <math> element, on its own line when `display`. */
+export function renderFormula(tex: string, display: boolean): string {
+  return temml.renderToString(tex, { displayMode: display, throwOnError: true });
+}

package/runtime/shared/text/markdown.ts

@@ -0,0 +1,185 @@
+// Restricted Markdown, the format of every learner text with formatting: paragraphs, **bold**, *italics*, lists,
+// links, line breaks and formulas as $…$. Everything else Markdown knows is a problem with the block to use instead,
+// so that structure comes only from section blocks and the heading levels from the nesting. Raw HTML is a problem
+// too. Rendered at build time; formulas become MathML.
+import { Marked, type Token, type Tokens } from "marked";
+import { formulaProblem, renderFormula } from "./formula.ts";
+import { escape } from "../html.ts";
+
+/** A problem in a text, `line` lines below its first. */
+export interface TextProblem {
+  line: number;
+  message: string;
+}
+
+/** What a text holds besides its prose: its problems, the formulas and the targets of its links. */
+export interface Inspection {
+  problems: TextProblem[];
+  formulas: string[];
+  links: string[];
+}
+
+interface MathToken extends Tokens.Generic {
+  type: "math";
+  raw: string;
+  tex: string;
+}
+
+/** Where a link leads from the page being rendered; set for each render. */
+let resolveLink: (href: string) => string = (href) => href;
+
+const marked = new Marked({
+  gfm: true,
+  breaks: false,
+  extensions: [
+    {
+      name: "math",
+      level: "inline",
+      start(source: string) {
+        const at = source.indexOf("$");
+        return at < 0 ? undefined : at;
+      },
+      tokenizer(source: string): MathToken | undefined {
+        const match = /^\$((?:\\.|[^\\$\n])+?)\$/.exec(source);
+        return match === null ? undefined : { type: "math", raw: match[0], tex: match[1] ?? "" };
+      },
+      renderer(token: Tokens.Generic) {
+        return renderFormula(String(token["tex"]), false);
+      },
+    },
+  ],
+  renderer: {
+    html(token) {
+      return escape(token.text);
+    },
+    link({ href, tokens }) {
+      const text = this.parser.parseInline(tokens);
+      const external = /^https?:\/\//.test(href);
+      return `<a href="${escape(external ? href : resolveLink(href))}"${external ? ' rel="noopener"' : ""}>${text}</a>`;
+    },
+  },
+});
+
+/** What each construct outside restricted Markdown is, and what to use instead. */
+const NOT_ALLOWED: Readonly<Record<string, string>> = {
+  blockquote: "a quotation in Markdown; use a quote block",
+  code: "code in a text; use a code block",
+  codespan: "code in a text; use a code block, or $…$ for a formula",
+  def: "a link definition; write the link in place: [text](url)",
+  del: "strikethrough is not part of restricted Markdown",
+  hr: "a horizontal rule; structure the page with section blocks",
+  image: "an image in a text; use a figure block",
+  table: "a table in Markdown; use a table block",
+  checkbox: "a task list is not part of restricted Markdown",
+};
+const ALLOWED = new Set([
+  "space",
+  "paragraph",
+  "text",
+  "list",
+  "list_item",
+  "strong",
+  "em",
+  "link",
+  "escape",
+  "br",
+  "math",
+]);
+
+function children(token: Token): Token[] {
+  const nested: Token[] = [];
+  if ("tokens" in token && Array.isArray(token.tokens)) nested.push(...(token.tokens as Token[]));
+  if (token.type === "list") nested.push(...token.items);
+  return nested;
+}
+
+/** The problems, formulas and links of a text in restricted Markdown. */
+export function inspect(source: string): Inspection {
+  const found: Inspection = { problems: [], formulas: [], links: [] };
+  const lineOf = (raw: string) => {
+    const at = source.indexOf(raw.trimStart());
+    return at < 0 ? 0 : source.slice(0, at).split("\n").length - 1;
+  };
+  const add = (raw: string, message: string) => {
+    if (!found.problems.some((problem) => problem.message === message)) {
+      found.problems.push({ line: lineOf(raw), message });
+    }
+  };
+  const visit = (tokens: Token[]) => {
+    for (const token of tokens) {
+      if (token.type === "heading") {
+        const title = (token as Tokens.Heading).text.trim();
+        add(token.raw, `a Markdown heading ("${title}"); use a section block with the title "${title}"`);
+      } else if (token.type === "html") {
+        const tag = /^<\/?([a-zA-Z][\w-]*)/.exec(token.raw.trim())?.[1] ?? "";
+        const first = found.problems.some((problem) => problem.message.startsWith("raw HTML"));
+        if (!first) {
+          add(
+            token.raw,
+            `raw HTML (<${tag}>) is not allowed; write restricted Markdown: **bold**, *italics*, lists, links`,
+          );
+        }
+      } else if (token.type === "math") {
+        const tex = String((token as MathToken).tex);
+        found.formulas.push(tex);
+        const problem = formulaProblem(tex);
+        if (problem !== undefined) add(token.raw, `$${tex}$: ${problem}`);
+      } else if (token.type === "link") {
+        const href = (token as Tokens.Link).href;
+        if (/^https?:\/\/\S+$/.test(href) || href.startsWith("/")) found.links.push(href);
+        else {
+          add(
+            token.raw,
+            `the link ${href} leads nowhere a learner can follow; link to https://… or to a page of the app: /<chapter>/<page>/`,
+          );
+        }
+      } else if (!ALLOWED.has(token.type)) {
+        add(token.raw, NOT_ALLOWED[token.type] ?? `${token.type} is not part of restricted Markdown`);
+      }
+      visit(children(token));
+    }
+  };
+  visit(marked.lexer(source));
+  return found;
+}
+
+/** A text in restricted Markdown as HTML; links to pages of the app go through `resolve`. */
+export function renderMarkdown(source: string, resolve: (href: string) => string): string {
+  resolveLink = resolve;
+  return marked.parse(source, { async: false }).trim();
+}
+
+/** A short text in restricted Markdown as HTML without a paragraph around it, e.g. a table cell or a caption. */
+export function renderInline(source: string, resolve: (href: string) => string): string {
+  resolveLink = resolve;
+  return marked.parseInline(source, { async: false }).trim();
+}
+
+/** A plain text as HTML. */
+export const plain = escape;
+
+export const FORMULA = /\$((?:\\.|[^\\$\n])+?)\$/g;
+
+/** A plain text as HTML in which only $…$ is a formula (MathML); everything else stays text, as in a quiz. */
+export function renderWithFormulas(text: string): string {
+  let html = "";
+  let from = 0;
+  for (const match of text.matchAll(FORMULA)) {
+    html += escape(text.slice(from, match.index)) + renderFormula(match[1] ?? "", false);
+    from = match.index + match[0].length;
+  }
+  return html + escape(text.slice(from));
+}
+
+/** What is wrong with the formulas $…$ of a plain text; none when each is in the command list and parses. */
+export function formulaProblems(text: string): string[] {
+  return [...text.matchAll(FORMULA)].flatMap((match) => {
+    const problem = formulaProblem(match[1] ?? "");
+    return problem === undefined ? [] : [`$${match[1]}$: ${problem}`];
+  });
+}
+
+/** The first HTML tag in a plain text, if it has one. */
+export function htmlTag(text: string): string | undefined {
+  return /<\/?([a-zA-Z][\w-]*)[^>]*>/.exec(text)?.[1];
+}

package/runtime/shared/text/speech.ts

@@ -0,0 +1,39 @@
+// The text alternative of a formula, for a name a screen reader or the accessibility check can read where the page has
+// only MathML (an option of a choice whose text is a formula, see the label of its radio): Speech Rule Engine speaks
+// the MathML of the formula in the page's language. Build time only; the engine loads its rules for every language
+// of the runtime once, here, so that speaking a formula in any of them is then synchronous.
+// @ts-expect-error speech-rule-engine ships no types; the part this file uses is typed below (drop this line if it does)
+import untyped from "speech-rule-engine";
+import { isLanguage, LANGUAGES } from "../languages.ts";
+import { renderFormula } from "./formula.ts";
+import { FORMULA } from "./markdown.ts";
+
+/** The part of Speech Rule Engine that this file uses. */
+interface Engine {
+  /** Loads the rules of the locale; once loaded, switching to it takes effect at once. */
+  setupEngine(setup: { locale: string; domain: string; modality: string }): Promise<void>;
+  /** The words of a MathML string, in the locale set up last. */
+  toSpeech(mathml: string): string;
+}
+const SRE: Engine = untyped;
+
+const SPEECH = { domain: "clearspeak", modality: "speech" } as const;
+
+for (const locale of LANGUAGES) await SRE.setupEngine({ locale, ...SPEECH });
+
+/** The formula `tex` as words in `lang` (German for a language the runtime has no texts for), e.g. "2 hoch 7". */
+export function speakFormula(tex: string, lang: string): string {
+  // the rules of every language are loaded: switching to one takes effect at once
+  void SRE.setupEngine({ locale: isLanguage(lang) ? lang : "de", ...SPEECH });
+  return SRE.toSpeech(renderFormula(tex, false)).replace(/\s+/g, " ").trim();
+}
+
+/**
+ * The words of a text that is only formulas, $…$ (and space); undefined for any other text, which has words of its own
+ * for a name to be made of.
+ */
+export function formulaAlternative(text: string, lang: string): string | undefined {
+  const formulas = [...text.matchAll(FORMULA)];
+  if (formulas.length === 0 || text.replace(FORMULA, "").trim() !== "") return undefined;
+  return formulas.map((formula) => speakFormula(formula[1] ?? "", lang)).join(" ");
+}

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

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:lernapps:schema:text.v1",
+  "title": "A learner text",
+  "description": "The texts of the content of an app: a text, and restricted Markdown, each a string while German is the only language of the app, else a map of texts by language. The schemas of the quiz, of the explainer and of the blocks they share refer to it.",
+  "$defs": {
+    "text": {
+      "description": "A text for learners 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": "Restricted Markdown, as a text or a map of texts by language: paragraphs, **bold**, *italics*, lists, links and line breaks, formulas as $…$ in the formula command list. No headings (use a section block), no HTML, no images (use a figure block), no code (use a code block), no quotes (use a quote block), no tables (use a table block). A link to a page of the app starts with / and names it from the app's root: /<chapter>/<page>/#<section>.",
+      "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+    }
+  }
+}