@lernapps/app-templates 0.0.1 → 0.1.1

package/runtime/shared/blocks/blocks.css

@@ -0,0 +1,190 @@
+/* The look of blocks that show content (text, formula, figure, labelled figure, table, quotation, code), for every
+   archetype that shows them, in the colours of the page (page.css): images that fit the page, the drawings, the
+   caption and the credit, the markers of a labelled figure, tables that scroll on their own, and code, highlighted at
+   build time (highlight.js classes), every colour with 4.5:1 on the code's background. */
+
+:root {
+  --block-hl-keyword: #7b2382;
+  --block-hl-string: #0f5a2e;
+  --block-hl-number: #8a3b00;
+  --block-hl-comment: #50555c;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --block-hl-keyword: #e0a3ff;
+    --block-hl-string: #8fe0ac;
+    --block-hl-number: #ffb77a;
+    --block-hl-comment: #a3a9b3;
+  }
+}
+
+.block-figure {
+  margin: 1.25rem 0;
+}
+
+.block-figure img,
+.block-drawing {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}
+
+.block-hundred-grid {
+  width: 16rem;
+}
+
+.block-bar {
+  width: 100%;
+  max-width: 28rem;
+}
+
+figcaption {
+  margin-top: 0.5rem;
+  color: var(--page-muted);
+  font-size: 0.9375rem;
+}
+
+figcaption p {
+  margin: 0;
+}
+
+.block-credit {
+  display: block;
+  font-size: 0.875rem;
+}
+
+.block-labelled-image {
+  position: relative;
+  display: inline-block;
+  max-width: 100%;
+}
+
+/* an image without a size of its own (an SVG with only a viewBox) fills the width, as in a figure */
+.block-labelled-fill {
+  display: block;
+}
+
+.block-labelled-fill img {
+  width: 100%;
+}
+
+/* the legend of a figure whose labels name their markers: the marker leads each line, in place of the list's number */
+.block-legend-named {
+  list-style: none;
+  padding-left: 0;
+}
+
+.block-marker {
+  position: absolute;
+  transform: translate(-50%, -50%);
+  min-width: 1.6rem;
+  padding: 0 0.3rem;
+  border-radius: 1rem;
+  background: var(--page-text);
+  color: var(--page-background);
+  font-size: 0.875rem;
+  font-weight: 700;
+  line-height: 1.6rem;
+  text-align: center;
+}
+
+/* a formula wider than the page scrolls on its own; vertically, MathML may overhang its box by a pixel */
+.block-formula {
+  margin: 1rem 0;
+  padding: 0.25rem 0;
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+
+math {
+  font-size: 1.1em;
+}
+
+.block-quote,
+.block-code {
+  margin: 1.25rem 0;
+}
+
+.block-table {
+  margin: 1rem 0;
+  overflow-x: auto;
+}
+
+.block-table table {
+  border-collapse: collapse;
+}
+
+.block-table caption {
+  margin-bottom: 0.25rem;
+  font-weight: 600;
+  text-align: left;
+}
+
+.block-table th,
+.block-table td {
+  padding: 0.35rem 0.6rem;
+  border: 1px solid var(--page-border);
+  text-align: left;
+  vertical-align: top;
+}
+
+.block-table thead th,
+.block-table th[scope="row"] {
+  background: var(--page-surface);
+}
+
+.block-quote blockquote {
+  margin: 0;
+  padding: 0.25rem 1rem;
+  border-left: 4px solid var(--page-border);
+  font-style: italic;
+}
+
+.block-code pre {
+  margin: 0;
+  padding: 0.75rem 1rem;
+  overflow-x: auto;
+  border-radius: 0.5rem;
+  background: var(--page-surface);
+  font-size: 0.9375rem;
+  line-height: 1.45;
+}
+
+/* code, highlighted at build time (highlight.js classes); every colour has 4.5:1 on the code's background */
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-literal,
+.hljs-type {
+  color: var(--block-hl-keyword);
+}
+
+.hljs-string,
+.hljs-attr,
+.hljs-regexp {
+  color: var(--block-hl-string);
+}
+
+.hljs-number,
+.hljs-symbol {
+  color: var(--block-hl-number);
+}
+
+.hljs-comment,
+.hljs-meta {
+  color: var(--block-hl-comment);
+  font-style: italic;
+}
+
+.hljs-title,
+.hljs-function,
+.hljs-name,
+.hljs-built_in {
+  color: var(--page-accent);
+}
+
+.hljs-variable,
+.hljs-params,
+.hljs-tag {
+  color: var(--page-text);
+}

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

@@ -0,0 +1,432 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:lernapps:schema:blocks.v1",
+  "title": "Blocks that show content",
+  "description": "The blocks the quiz shows with a question and the explainer shows on a page alike: prose, a formula, a figure (drawn from data or a bundled image), a labelled figure (a bundled image with numbered labels), a table, a quotation and program code, with the credit of an image or a quotation. An image is a file in src/images/ of the app.",
+  "$defs": {
+    "credit": {
+      "description": "Where a bundled image or a quote comes from: the source (a URL or a citation) and its licence (an SPDX identifier such as CC-BY-SA-4.0, or \"gemeinfrei\").",
+      "type": "object",
+      "properties": {
+        "source": {
+          "description": "Where it comes from: a URL, the same in every language and shown as a link, or a citation, a text like any other: a string while German is the only language of the app, else a map of texts by language with every declared language, e.g. { de: eigene Zeichnung, en: own drawing }. Each language's page shows its own.",
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "\\S"
+            },
+            {
+              "type": "object",
+              "minProperties": 1,
+              "propertyNames": {
+                "pattern": "^[a-z]{2}$"
+              },
+              "additionalProperties": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S"
+              }
+            }
+          ]
+        },
+        "licence": {
+          "description": "Its licence: an SPDX identifier (CC-BY-SA-4.0, CC0-1.0, …), or gemeinfrei for a work in the public domain.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      }
+    },
+    "image": {
+      "description": "A bundled image file in src/images/, as a path from src/: images/<name>.svg (or .png, .jpg, .webp).",
+      "type": "string",
+      "pattern": "^images/[a-z0-9]+(-[a-z0-9]+)*\\.(svg|png|jpg|webp)$"
+    },
+    "drawing": {
+      "description": "A figure drawn from numbers at build, as inline SVG: hundred-grid (a field of 100 squares, filled of them shaded) or bar (a strip, part of whole shaded, with its percentage).",
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "enum": ["hundred-grid", "bar"]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "hundred-grid"
+              }
+            },
+            "required": ["kind"],
+            "type": "object"
+          },
+          "then": {
+            "required": ["filled"],
+            "properties": {
+              "filled": {
+                "description": "How many of the 100 squares are shaded.",
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 100
+              }
+            },
+            "type": "object"
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "bar"
+              }
+            },
+            "required": ["kind"],
+            "type": "object"
+          },
+          "then": {
+            "required": ["part", "whole"],
+            "properties": {
+              "part": {
+                "description": "The shaded part.",
+                "type": "number",
+                "minimum": 0
+              },
+              "whole": {
+                "description": "The whole strip, 100 %.",
+                "type": "number",
+                "exclusiveMinimum": 0
+              }
+            },
+            "type": "object"
+          }
+        }
+      ],
+      "unevaluatedProperties": false
+    },
+    "figure": {
+      "description": "A figure: drawn from data (draw) or a bundled image (image, with its source and licence), one of the two. It has an alternative text that says what it shows, and a caption that says what to see.",
+      "required": ["alt", "caption"],
+      "allOf": [
+        {
+          "$ref": "#/$defs/credit"
+        }
+      ],
+      "properties": {
+        "draw": {
+          "$ref": "#/$defs/drawing"
+        },
+        "image": {
+          "$ref": "#/$defs/image"
+        },
+        "alt": {
+          "description": "What the figure shows, for those who cannot see it.",
+          "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+        },
+        "caption": {
+          "description": "What to see in the figure, under it.",
+          "$ref": "urn:lernapps:schema:text.v1#/$defs/markdown"
+        }
+      },
+      "dependentRequired": {
+        "image": ["source", "licence"]
+      },
+      "type": "object"
+    },
+    "labelledFigure": {
+      "description": "A bundled image with labels at positions. Each label shows its marker (A, B, 1a; else its number in order). The texts of the labels are listed beside the image (the legend), unless legend is false.",
+      "required": ["image", "alt", "labels", "source", "licence"],
+      "allOf": [
+        {
+          "$ref": "#/$defs/credit"
+        }
+      ],
+      "properties": {
+        "image": {
+          "$ref": "#/$defs/image"
+        },
+        "alt": {
+          "description": "What the image shows, for those who cannot see it.",
+          "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+        },
+        "caption": {
+          "description": "What to see in the figure.",
+          "$ref": "urn:lernapps:schema:text.v1#/$defs/markdown"
+        },
+        "legend": {
+          "description": "Whether the texts of the labels are listed beside the image. Default true. With false the figure shows only the markers (for a figure the learner labels), and alt names every marker with its part.",
+          "type": "boolean"
+        },
+        "labels": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["x", "y", "text"],
+            "properties": {
+              "marker": {
+                "description": "What the label shows on the image, plain text of 1 to 3 characters (A, B, 1a), the letters of the material. Each marker is used once. Without it: the number of the label in order, from 1.",
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 3
+              },
+              "x": {
+                "description": "From the left edge, in percent of the width.",
+                "type": "number",
+                "minimum": 0,
+                "maximum": 100
+              },
+              "y": {
+                "description": "From the top edge, in percent of the height.",
+                "type": "number",
+                "minimum": 0,
+                "maximum": 100
+              },
+              "text": {
+                "description": "What the label names.",
+                "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+              }
+            }
+          }
+        }
+      },
+      "type": "object"
+    },
+    "materialBlock": {
+      "description": "A block that shows content with a question: a figure or a labelled figure.",
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "description": "The kind of block.",
+          "enum": ["text", "formula", "figure", "labelled-figure", "table", "quote", "code"]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "text"
+              }
+            },
+            "required": ["type"],
+            "type": "object"
+          },
+          "then": {
+            "$ref": "#/$defs/textBlock"
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "formula"
+              }
+            },
+            "required": ["type"],
+            "type": "object"
+          },
+          "then": {
+            "$ref": "#/$defs/formula"
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "figure"
+              }
+            },
+            "required": ["type"],
+            "type": "object"
+          },
+          "then": {
+            "$ref": "#/$defs/figure"
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "labelled-figure"
+              }
+            },
+            "required": ["type"],
+            "type": "object"
+          },
+          "then": {
+            "$ref": "#/$defs/labelledFigure"
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "table"
+              }
+            },
+            "required": ["type"],
+            "type": "object"
+          },
+          "then": {
+            "$ref": "#/$defs/table"
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "quote"
+              }
+            },
+            "required": ["type"],
+            "type": "object"
+          },
+          "then": {
+            "$ref": "#/$defs/quote"
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "code"
+              }
+            },
+            "required": ["type"],
+            "type": "object"
+          },
+          "then": {
+            "$ref": "#/$defs/code"
+          }
+        }
+      ],
+      "unevaluatedProperties": false
+    },
+    "textBlock": {
+      "description": "Prose in restricted Markdown.",
+      "required": ["text"],
+      "properties": {
+        "text": {
+          "$ref": "urn:lernapps:schema:text.v1#/$defs/markdown"
+        }
+      },
+      "type": "object"
+    },
+    "formula": {
+      "description": "One formula on its own line, rendered at build to MathML.",
+      "required": ["formula"],
+      "properties": {
+        "formula": {
+          "$ref": "#/$defs/latex"
+        }
+      },
+      "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.",
+      "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+    },
+    "table": {
+      "description": "A table with a caption. Cells are restricted Markdown without paragraphs.",
+      "required": ["caption", "rows"],
+      "properties": {
+        "caption": {
+          "description": "What the table shows.",
+          "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+        },
+        "header": {
+          "description": "The header row: one heading per column.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "urn:lernapps:schema:text.v1#/$defs/markdown"
+          }
+        },
+        "rowHeaders": {
+          "description": "The first cell of each row heads the row.",
+          "type": "boolean",
+          "default": false
+        },
+        "rows": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "$ref": "urn:lernapps:schema:text.v1#/$defs/markdown"
+            }
+          }
+        }
+      },
+      "type": "object"
+    },
+    "quote": {
+      "description": "A quotation, quoted exactly, with its origin, source and licence.",
+      "required": ["text", "origin", "source", "licence"],
+      "allOf": [
+        {
+          "$ref": "#/$defs/credit"
+        }
+      ],
+      "properties": {
+        "text": {
+          "description": "The quotation itself, exactly as written.",
+          "$ref": "urn:lernapps:schema:text.v1#/$defs/markdown"
+        },
+        "origin": {
+          "description": "Who said or wrote it, where and when.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["author"],
+          "properties": {
+            "author": {
+              "description": "Who said or wrote it. A name is the same in every language: a string, or a map by language where it differs.",
+              "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+            },
+            "work": {
+              "description": "Where it was said or written: the work, as it is called; a string, or a map by language where its title is translated.",
+              "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+            },
+            "year": {
+              "anyOf": [
+                {
+                  "type": "integer"
+                },
+                {
+                  "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+                }
+              ],
+              "description": "When: a year, or a text such as um 500 v. Chr."
+            }
+          }
+        }
+      },
+      "type": "object"
+    },
+    "code": {
+      "description": "Program code, highlighted at build.",
+      "required": ["language", "code"],
+      "properties": {
+        "language": {
+          "enum": ["bash", "c", "css", "html", "java", "javascript", "json", "plaintext", "python", "sql", "typescript"]
+        },
+        "code": {
+          "description": "The code, as it is.",
+          "type": "string",
+          "minLength": 1
+        },
+        "caption": {
+          "description": "What the code does.",
+          "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+        }
+      },
+      "type": "object"
+    }
+  }
+}

package/runtime/shared/blocks/code.ts

@@ -0,0 +1,26 @@
+// Code blocks, highlighted at build time by highlight.js into spans with classes (blocks.css colours them): the
+// page needs no script for it. The languages are a fixed list, the schema's $defs/code.
+import hljs from "highlight.js/lib/core";
+import bash from "highlight.js/lib/languages/bash";
+import c from "highlight.js/lib/languages/c";
+import css from "highlight.js/lib/languages/css";
+import java from "highlight.js/lib/languages/java";
+import javascript from "highlight.js/lib/languages/javascript";
+import json from "highlight.js/lib/languages/json";
+import python from "highlight.js/lib/languages/python";
+import sql from "highlight.js/lib/languages/sql";
+import typescript from "highlight.js/lib/languages/typescript";
+import xml from "highlight.js/lib/languages/xml";
+import { escapeText } from "../html.ts";
+
+const languages = { bash, c, css, html: xml, java, javascript, json, python, sql, typescript };
+for (const [name, language] of Object.entries(languages)) hljs.registerLanguage(name, language);
+
+/** The languages a code block may have. */
+export type CodeLanguage = keyof typeof languages | "plaintext";
+
+/** The code as highlighted HTML, for inside <code>. */
+export function highlight(code: string, language: CodeLanguage): string {
+  if (language === "plaintext") return escapeText(code);
+  return hljs.highlight(code, { language, ignoreIllegals: true }).value;
+}

package/runtime/shared/blocks/figures.ts

@@ -0,0 +1,49 @@
+// The figures drawn from data at build time, as inline SVG with role="img" and the figure's alternative text as its
+// name: hundred-grid (a field of 100 squares, some shaded) and bar (a strip with a shaded part and its percentage).
+import { escape } from "../html.ts";
+
+const ON = "#1d4ed8";
+const OFF = "#ffffff";
+const LINE = "#4a4a4a";
+
+/** A field of 10 × 10 squares, the first `filled` shaded, row by row. */
+export function hundredGrid(filled: number, alt: string): string {
+  const cells: string[] = [];
+  for (let index = 0; index < 100; index++) {
+    const x = 1 + (index % 10) * 11;
+    const y = 1 + Math.floor(index / 10) * 11;
+    cells.push(
+      `<rect x="${x}" y="${y}" width="10" height="10" class="${index < filled ? "fig-on" : "fig-off"} fig-line" fill="${index < filled ? ON : OFF}" stroke="${LINE}" stroke-width="0.5"/>`,
+    );
+  }
+  return `<svg class="block-drawing block-hundred-grid" role="img" aria-label="${escape(alt)}" viewBox="0 0 111 111" xmlns="http://www.w3.org/2000/svg">${cells.join("")}</svg>`;
+}
+
+/**
+ * A strip for `whole`, `part` of it shaded; under it 0, part and whole, and their percentages (without them in a task
+ * that asks for the percentage: `percent` false).
+ */
+export function bar(part: number, whole: number, alt: string, locale: string, percent = true): string {
+  const numbers = new Intl.NumberFormat(locale, { maximumFractionDigits: 2 });
+  const share = Math.min(part / whole, 1);
+  const width = 298 * share;
+  const at = Math.min(Math.max(1 + width, 50), 250);
+  const label = (x: number, y: number, anchor: string, text: string) =>
+    `<text x="${x.toFixed(1)}" y="${y}" text-anchor="${anchor}" font-size="12" class="fig-text" fill="#1a1a1a">${escape(text)}</text>`;
+  return [
+    `<svg class="block-drawing block-bar" role="img" aria-label="${escape(alt)}" viewBox="0 0 300 ${percent ? 74 : 58}" xmlns="http://www.w3.org/2000/svg">`,
+    `<rect x="1" y="1" width="298" height="36" class="fig-off fig-line" fill="${OFF}" stroke="${LINE}"/>`,
+    `<rect x="1" y="1" width="${width.toFixed(1)}" height="36" class="fig-on" fill="${ON}"/>`,
+    label(1, 54, "start", "0"),
+    label(at, 54, "middle", numbers.format(part)),
+    label(299, 54, "end", numbers.format(whole)),
+    ...(percent
+      ? [
+          label(1, 70, "start", "0 %"),
+          label(at, 70, "middle", `${numbers.format(share * 100)} %`),
+          label(299, 70, "end", "100 %"),
+        ]
+      : []),
+    `</svg>`,
+  ].join("");
+}