@lernapps/app-templates 0.0.1 → 0.1.0

package/runtime/explainer/result.ts

@@ -0,0 +1,238 @@
+// The result line that "Zurück" copies on a page a tutor opened (explainer.ts). The app sends nothing and reports
+// nothing back: the tutor learns only what the learner writes into the chat, so the button puts the line on the
+// clipboard for the learner to paste there. It names the page, the exercise and its task number, how far the learner
+// got with it ("richtig im 2. Versuch", "Lösung angesehen", "noch nicht gelöst (1 Versuch, Eingabe 3/20)"), the count
+// of the session on this page, and the absolute address of the page's tutor page with the position (position.ts),
+// which holds the task (tutorpage.ts): a chat assistant fetches only addresses its user wrote into the conversation,
+// so the learner brings it. The solution is never in the line, as the learner reads it while pasting. Pure and
+// without Node: the client module calls it.
+import { rightEntries, type Answer, type Question } from "../shared/questions/question.ts";
+import { message } from "./messages.ts";
+
+/**
+ * How far the learner got with one task: the tries, the try that was right, the solution viewed, the last wrong input
+ * with the message the app showed for it, word for word, and whether the learner opened the hint.
+ */
+export interface TaskState {
+  attempts: number;
+  rightAt?: number;
+  revealed: boolean;
+  input?: string;
+  message?: string;
+  hint?: boolean;
+  /** For an open task not all right: how many of its points the learner ticked, of how many, and the missed ones (P1). */
+  points?: { ticked: number; total: number; missed: string };
+}
+
+/** The count of the session: the tasks answered right, of all the learner answered or looked up. */
+export interface Session {
+  right: number;
+  total: number;
+}
+
+const key = (id: string, n: number | undefined) => (n === undefined ? id : `${id}=${n}`);
+
+/**
+ * What the learner did on this page, by task (an exercise and its task number), kept in memory only: the page stores
+ * nothing, so the session is this visit of the page, which a tutor's link opens in a tab of its own.
+ */
+export class Progress {
+  readonly #tasks = new Map<string, TaskState>();
+  readonly #listeners: ((id: string) => void)[] = [];
+  #last: string | undefined;
+
+  /** Calls `listener` with the exercise's id whenever the state of one of its tasks changes. */
+  listen(listener: (id: string) => void): void {
+    this.#listeners.push(listener);
+  }
+
+  #set(id: string, n: number | undefined, state: TaskState): void {
+    this.#tasks.set(key(id, n), state);
+    for (const listener of this.#listeners) listener(id);
+  }
+
+  /**
+   * A complete answer to the task number `n` of the exercise `id` (none for an exercise without numbers): the input as
+   * text, and the message the app showed for a wrong one, word for word.
+   */
+  answered(id: string, n: number | undefined, right: boolean, input?: string, message?: string): void {
+    this.#last = id;
+    const state = this.state(id, n);
+    // once the task is right or its solution shown, nothing after counts
+    if (state.rightAt !== undefined || state.revealed) return;
+    const attempts = state.attempts + 1;
+    const { input: _input, message: _message, ...rest } = state;
+    this.#set(id, n, {
+      ...rest,
+      attempts,
+      ...(right ? { rightAt: attempts } : {}),
+      ...(right || input === undefined ? {} : { input }),
+      ...(right || message === undefined || message === "" ? {} : { message }),
+    });
+  }
+
+  /**
+   * The open task `id` as the learner compared it: `ticked` of `total` points, the `missed` ones named (P2, P4), the
+   * answer as text (or that it is a photo). `attempt`: a new comparing, which counts as a try; a changed tick changes
+   * the same try. Its model answer shows once compared.
+   */
+  compared(id: string, ticked: number, total: number, missed: string, input: string, attempt = true): void {
+    this.#last = id;
+    const state = this.state(id, undefined);
+    const attempts = attempt ? state.attempts + 1 : Math.max(state.attempts, 1);
+    const { points: _points, input: _input, rightAt: _rightAt, ...rest } = state;
+    this.#set(id, undefined, {
+      ...rest,
+      attempts,
+      revealed: true,
+      ...(ticked === total ? { rightAt: attempts } : { points: { ticked, total, missed }, input }),
+    });
+  }
+
+  /** The learner opened the hint of the task. */
+  hinted(id: string, n: number | undefined): void {
+    const state = this.state(id, n);
+    if (state.hint === true) return;
+    this.#set(id, n, { ...state, hint: true });
+  }
+
+  /** The solution of the task shows ("Lösung"; also after the right answer, which then stays right). */
+  revealed(id: string, n: number | undefined): void {
+    this.#last = id;
+    const state = this.state(id, n);
+    if (state.rightAt !== undefined) return;
+    this.#set(id, n, { ...state, revealed: true });
+  }
+
+  /** How far the learner got with the task. */
+  state(id: string, n: number | undefined): TaskState {
+    return this.#tasks.get(key(id, n)) ?? { attempts: 0, revealed: false };
+  }
+
+  /** The exercise the learner answered last, if any. */
+  get last(): string | undefined {
+    return this.#last;
+  }
+
+  /** Each task the learner answered or looked up in this session, in the order they first did. */
+  tasks(): { id: string; number?: number; state: TaskState }[] {
+    return [...this.#tasks.entries()]
+      .filter(([, state]) => state.attempts > 0 || state.revealed)
+      .map(([key, state]) => {
+        const [id = "", n] = key.split("=");
+        return { id, ...(n === undefined ? {} : { number: Number(n) }), state };
+      });
+  }
+
+  /** The count of the session. */
+  session(): Session {
+    // a hint alone does not count: the learner neither answered nor looked up the task
+    const states = [...this.#tasks.values()].filter((state) => state.attempts > 0 || state.revealed);
+    return { right: states.filter((state) => state.rightAt !== undefined).length, total: states.length };
+  }
+}
+
+/** What one result line says. */
+export interface ResultLine {
+  /** The page's title. */
+  page: string;
+  /** The exercise's id. */
+  exercise: string;
+  /** The task number, for an exercise with numbers. */
+  number?: number;
+  state: TaskState;
+  session: Session;
+  /** The page's tutor page with the position, absolute. */
+  tutor: string;
+}
+
+/** How far the learner got with a task, in `lang`: "richtig im 2. Versuch", "noch nicht gelöst (1 Versuch, …)". */
+function statusOf(state: TaskState, lang: string): string {
+  if (state.rightAt !== undefined) return message(lang, "resultRight", { n: String(state.rightAt) });
+  if (state.points !== undefined) {
+    const partly = message(lang, "resultPartly", {
+      n: String(state.points.ticked),
+      total: String(state.points.total),
+      missed: state.points.missed,
+    });
+    return state.input === undefined ? partly : `${partly}, ${message(lang, "resultAnswer", { input: state.input })}`;
+  }
+  const status = message(lang, state.revealed ? "resultSolution" : "resultOpen");
+  if (state.attempts === 0) return status;
+  const tries =
+    state.attempts === 1 ? message(lang, "resultTry") : message(lang, "resultTries", { n: String(state.attempts) });
+  const input = state.input === undefined ? "" : `, ${message(lang, "resultInput", { input: state.input })}`;
+  return `${status} (${tries}${input})`;
+}
+
+/**
+ * What "Zurück zum Tutor" at the top or the end of a page copies, in `lang`: the page's tutor page with the page's
+ * task numbers, then a line for each task the learner answered or looked up in this session (the exercise, its task
+ * number, how far the learner got, the last wrong input and the app's message for it, word for word), then the count of
+ * the session; a tutor loads the tutor page and coaches on exactly these tasks.
+ */
+export function sessionLines(
+  tutor: string,
+  tasks: readonly { id: string; number?: number; state: TaskState }[],
+  session: Session,
+  lang: string,
+): string {
+  if (tasks.length === 0) return message(lang, "sessionNone", { url: tutor });
+  return [
+    message(lang, "sessionIntro", { url: tutor }),
+    ...tasks.map((task) => {
+      const said =
+        task.state.rightAt === undefined && task.state.message !== undefined
+          ? ` ${message(lang, "stuckMessage", { message: task.state.message.replace(/\s+/g, " ").trim() })}`
+          : "";
+      return `- ${message(lang, "sessionTask", {
+        exercise: task.id,
+        number: task.number === undefined ? "" : message(lang, "resultNumber", { n: String(task.number) }),
+        status: statusOf(task.state, lang),
+      })}${said}`;
+    }),
+    message(lang, "resultSession", { right: String(session.right), total: String(session.total) }),
+  ].join("\n");
+}
+
+/** The result line, two lines in `lang`: the result, and the page's tutor page. */
+export function resultLine(line: ResultLine, lang: string): string {
+  const first = message(lang, "resultLine", {
+    page: line.page,
+    exercise: line.exercise,
+    number: line.number === undefined ? "" : message(lang, "resultNumber", { n: String(line.number) }),
+    status: statusOf(line.state, lang),
+  });
+  const session =
+    line.session.total === 0
+      ? ""
+      : ` ${message(lang, "resultSession", { right: String(line.session.right), total: String(line.session.total) })}`;
+  return [`${first}${session}`, `${message(lang, "resultTutor")} ${line.tutor}`].join("\n");
+}
+
+const oneLine = (text: string) => text.replace(/\s+/g, " ").trim();
+
+/** The learner's answer to a question as text, in `lang`: the options chosen, the number typed, the order given. */
+export function answerShown(question: Question, answer: Answer, lang: string): string {
+  const indices = typeof answer === "number" ? [answer] : Array.isArray(answer) ? (answer as readonly number[]) : [];
+  switch (question.type) {
+    case "single-choice":
+    case "multiple-choice":
+      return indices.map((index) => oneLine(question.options[index]?.text ?? "?")).join("; ");
+    case "true-false":
+      return message(lang, answer === true ? "resultTrue" : "resultFalse");
+    case "number":
+      return oneLine(String(answer));
+    case "ordering":
+      return indices
+        .map((place, item) => ({ place, item }))
+        .filter(({ place }) => place >= 0)
+        .sort((a, b) => a.place - b.place)
+        .map(({ item }) => oneLine(question.items[item] ?? "?"))
+        .join(" → ");
+    case "matching":
+      return question.pairs
+        .map((pair, index) => `${oneLine(pair.left)} → ${oneLine(rightEntries(question)[indices[index] ?? -1] ?? "?")}`)
+        .join("; ");
+  }
+}

package/runtime/explainer/routes.ts

@@ -0,0 +1,119 @@
+// The pages an explainer's build writes, per language, and how they link: the start page, a page per chapter (none
+// when the app has one chapter, which the navigation then hides), the content pages in the order of the lists, the
+// glossary when the content defines terms, and the page of each self-assessment (assessment.ts), linked only from
+// the start page or its chapter's page. German is at the root, every other language below /<language>/;
+// within a language tree the addresses are the same: <chapter>/<page>/, glossar/.
+import {
+  allBlocks,
+  inLanguage,
+  termId,
+  type BlockOf,
+  type Chapter,
+  type Page,
+  type Site,
+  type Text,
+} from "./content.ts";
+import { languageRoot } from "../shared/pages.ts";
+import { message } from "./messages.ts";
+import { assessments, type Assessment } from "./assessment.ts";
+
+export interface Route {
+  kind: "start" | "chapter" | "page" | "glossary" | "assessment";
+  lang: string;
+  /** Where the page is, from the app's root: "", "prozent/", "en/prozent/prozentwert/", "glossar/". */
+  path: string;
+  /** The same page's address within any language tree: "", "prozent/prozentwert/". */
+  local: string;
+  /** Its title, the h1. */
+  title: string;
+  chapter?: Chapter;
+  page?: Page;
+  /** The self-assessment of the page of kind assessment. */
+  assessment?: Assessment;
+}
+
+/** Whether the app's one chapter is hidden in the navigation. */
+export const hiddenChapter = (site: Site): boolean => site.chapters.length === 1;
+
+/** The content pages in order, over all chapters. */
+export const contentPages = (site: Site): Page[] => site.chapters.flatMap((chapter) => chapter.pages);
+
+/** A definition of the content, where it is. */
+export interface Term {
+  id: string;
+  term: Text;
+  explanation: Text;
+  page: Page;
+}
+
+export { allBlocks };
+
+/** The terms the content defines, in the order of the pages. */
+export function terms(site: Site): Term[] {
+  return contentPages(site).flatMap((page) =>
+    [...allBlocks(page.blocks)]
+      .filter((block): block is BlockOf<"definition"> => block.type === "definition")
+      .map((block) => ({ id: termId(block.term), term: block.term, explanation: block.explanation, page })),
+  );
+}
+
+/** Every page of the app, in every language. */
+export function routes(site: Site): Route[] {
+  const hidden = hiddenChapter(site);
+  const glossary = terms(site).length > 0;
+  const all = assessments(site);
+  return site.app.languages.flatMap((lang) => {
+    const root = languageRoot(lang);
+    const list: Route[] = [{ kind: "start", lang, path: root, local: "", title: inLanguage(site.app.title, lang) }];
+    const assessmentRoute = (assessment: Assessment): Route => ({
+      kind: "assessment",
+      lang,
+      path: root + assessment.local,
+      local: assessment.local,
+      title: message(lang, "assessmentTitle"),
+      ...(assessment.chapter === undefined ? {} : { chapter: assessment.chapter }),
+      assessment,
+    });
+    for (const assessment of all.filter((candidate) => candidate.chapter === undefined)) {
+      list.push(assessmentRoute(assessment));
+    }
+    for (const chapter of site.chapters) {
+      if (!hidden) {
+        const local = `${chapter.id}/`;
+        list.push({
+          kind: "chapter",
+          lang,
+          path: root + local,
+          local,
+          title: inLanguage(chapter.title, lang),
+          chapter,
+        });
+        for (const assessment of all.filter((candidate) => candidate.chapter === chapter)) {
+          list.push(assessmentRoute(assessment));
+        }
+      }
+      for (const page of chapter.pages) {
+        const local = `${chapter.id}/${page.id}/`;
+        list.push({
+          kind: "page",
+          lang,
+          path: root + local,
+          local,
+          title: inLanguage(page.title, lang),
+          chapter,
+          page,
+        });
+      }
+    }
+    if (glossary) {
+      list.push({
+        kind: "glossary",
+        lang,
+        path: `${root}glossar/`,
+        local: "glossar/",
+        title: message(lang, "glossary"),
+      });
+    }
+    return list;
+  });
+}

package/runtime/explainer/schema.ts

@@ -0,0 +1,140 @@
+// 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
+// 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 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";
+
+// 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}`);
+  return validate;
+};
+export const validators = {
+  app: validator("app"),
+  chapter: validator("chapter"),
+  page: validator("page"),
+  data: validator("data"),
+  event: validator("event"),
+};
+
+const schemas = schemasById(...questionSchemas, schema);
+
+const BLOCK_DEFINITIONS: Readonly<Record<string, string>> = {
+  text: "textBlock",
+  formula: "formula",
+  figure: "figure",
+  "labelled-figure": "labelledFigure",
+  table: "table",
+  timeline: "timeline",
+  definition: "definition",
+  quote: "quote",
+  code: "code",
+  video: "video",
+  example: "box",
+  note: "box",
+  section: "section",
+  generated: "generated",
+  "open-task": "openTask",
+  "vue-component": "vueComponent",
+};
+
+/** The fields of an exercise of a question type: those of every question and those of its type. */
+const questionFields = (type: string): Set<string> => {
+  const own = knownProperties(schemas, questionSchema.$id, "question", { branches: false });
+  const branch = knownProperties(schemas, questionSchema.$id, QUESTION_BRANCH[type] ?? "");
+  return new Set([...own, ...branch]);
+};
+
+/** 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 === "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`;
+  }
+  if (property === "licence" || property === "source") {
+    return `${property} is missing; a bundled image names its source and its licence`;
+  }
+  return `${property} is missing`;
+}
+
+/** The explainer's own words for the errors of its schema: what a block or an exercise lacks, or may not have. */
+const describe: DescribeError = (error, path, value) => {
+  switch (error.keyword) {
+    case "anyOf": {
+      // the address of a link of an exercise of the question types: an https address, or a map of them by language
+      if (path.at(-1) !== "url") return undefined;
+      const { lang, message } = addressProblem(value);
+      return { message, ...(lang === undefined ? {} : { lang }) };
+    }
+    case "pattern":
+      // 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>` };
+      }
+      // a video's id: an address pasted whole is the likely mistake
+      if (path.at(-1) !== "youtube") return undefined;
+      return {
+        message: `${String(value)} is no YouTube id; give the 11 characters after watch?v= in the video's address, e.g. rkLmLaFHodo`,
+      };
+    case "required":
+    case "dependentRequired":
+      return { message: missing(String(error.params["missingProperty"]), value) };
+    case "unevaluatedProperties": {
+      const property = String(error.params["unevaluatedProperty"]);
+      const type = isObject(value) ? value["type"] : undefined;
+      const kind = isObject(value) ? value["kind"] : undefined;
+      const definition =
+        path.at(-1) === "draw"
+          ? "drawing"
+          : typeof type === "string"
+            ? BLOCK_DEFINITIONS[type]
+            : typeof kind === "string"
+              ? "drawing"
+              : undefined;
+      if (typeof type === "string" && type in QUESTION_BRANCH) {
+        return questionFields(type).has(property)
+          ? null
+          : { message: `${property} is not a field of a ${type} exercise` };
+      }
+      if (
+        definition === undefined ||
+        property === "type" ||
+        knownProperties(schemas, schema.$id, definition).has(property)
+      )
+        return null;
+      const what = path.at(-1) === "draw" ? `a ${String(kind)} drawing` : `a ${String(type)} block`;
+      return { message: `${property} is not a field of ${what}` };
+    }
+    case "enum":
+      if (path.at(-1) !== "type") return undefined;
+      return {
+        path: path.slice(0, -1),
+        message: `${String(value)} is not a block type; use one of ${(error.params["allowedValues"] as string[]).join(", ")}`,
+      };
+  }
+  return undefined;
+};
+
+export 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, describe);
+  // every error folded away: the file is still invalid
+  if (problems.lines.length === before) problems.at(yaml, [], "does not match the schema");
+  return false;
+}

package/runtime/explainer/scope.ts

@@ -0,0 +1,87 @@
+// The scope of an explainer, for the tutor: the whole learning path in the creator's own words, from the material, as
+// continuous prose. Each content page says what it teaches (`scope` in its YAML), a chapter may say what it is about as
+// a whole, and src/app.yaml says what the app is about and what does not belong to the scope (`scope: { text, out }`;
+// what belongs to it is what the pages say); with the app's, every page has its own (load.ts checks it). The build
+// writes, in each language tree, a scope beside each content page, <chapter>/<page>/scope/: the page's text and what
+// does not belong to the scope, with a link to its chapter's; beside each chapter, <chapter>/scope/: its text and its pages', with a link to
+// the app's; and the whole at scope/. Each as its Markdown (index.md) and a page that no menu links (index.html,
+// noindex). Each tutor page links its page's scope (../scope/), so that a tutor judges an open answer by the material,
+// not by general knowledge, and goes up to the chapter or the app when a point's source is on another page. The
+// learner never sees it.
+import { renderMarkdown } from "../shared/text/markdown.ts";
+import { escape } from "../shared/html.ts";
+import { inLanguage, type Site, type Text } from "./content.ts";
+
+/** The folder of a scope, below the app's root, a chapter's folder or a page's folder in each language tree. */
+export const SCOPE_PAGE = "scope/";
+
+/** The words of a scope by language: its closing part and the links one level up. */
+const WORDS = {
+  de: {
+    out: "Gehört nicht dazu",
+    chapter: "Alle Seiten des Kapitels: [Scope des Kapitels](../../scope/)",
+    app: "Die ganze App: [Scope der App](../../scope/)",
+  },
+  en: {
+    out: "Out of scope",
+    chapter: "All pages of the chapter: [scope of the chapter](../../scope/)",
+    app: "The whole app: [scope of the app](../../scope/)",
+  },
+} as const;
+
+/**
+ * The scopes the build writes for `site` in `lang`, by their folder within the language tree: "" the whole,
+ * "<chapter>/" a chapter's with its pages, "<chapter>/<page>/" a page's; each but the whole with a link one level up.
+ * None when the app has no scope.
+ */
+export function scopeFiles(site: Site, lang: string): Map<string, string> {
+  const files = new Map<string, string>();
+  const { scope } = site.app;
+  if (scope === undefined) return files;
+  const words = lang === "de" ? WORDS.de : WORDS.en;
+  const own = (text: Text | undefined) => (text === undefined ? "" : inLanguage(text, lang).trim());
+  const closing = [`## ${words.out}`, scope.out.map((item) => `- ${own(item)}`).join("\n")];
+  const join = (...parts: string[]) => `${parts.filter((part) => part !== "").join("\n\n")}\n`;
+  const whole: string[] = [`# ${own(site.app.title)}`, own(scope.text)];
+  for (const chapter of site.chapters) {
+    const pages = chapter.pages.map((page) => ({ page, title: own(page.title), text: own(page.scope) }));
+    whole.push(`## ${own(chapter.title)}`, own(chapter.scope));
+    for (const { title, text } of pages) whole.push(`### ${title}`, text);
+    files.set(
+      `${chapter.id}/`,
+      join(
+        `# ${own(chapter.title)}`,
+        own(chapter.scope),
+        ...pages.flatMap(({ title, text }) => [`## ${title}`, text]),
+        ...closing,
+        words.app,
+      ),
+    );
+    for (const { page, title, text } of pages) {
+      files.set(`${chapter.id}/${page.id}/`, join(`# ${title}`, text, ...closing, words.chapter));
+    }
+  }
+  files.set("", join(...whole, ...closing));
+  return files;
+}
+
+/** The page of the scope in `folder` (as scopeFiles names it) in `lang`: its Markdown rendered, for no menu and no search engine. */
+export function scopeDocument(markdown: string, title: string, lang: string, folder = ""): string {
+  // a link of the scope to a page leads within the language tree, from <folder>scope/
+  const depth = folder.split("/").filter((segment) => segment !== "").length + 1;
+  const body = renderMarkdown(markdown, (href) =>
+    href.startsWith("/") ? `${"../".repeat(depth)}${href.slice(1)}` : href,
+  );
+  return [
+    "<!doctype html>",
+    `<html lang="${escape(lang)}">`,
+    "<head>",
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    '<meta name="robots" content="noindex">',
+    `<title>${escape(title)}</title>`,
+    "</head>",
+    `<body><main>${body}</main></body>`,
+    "</html>",
+  ].join("\n");
+}

package/runtime/explainer/stuck.ts

@@ -0,0 +1,57 @@
+// "Hilfe" ("Warum?" after a wrong answer), way B to the tutor (explainer.ts): the learner is stuck at one task. The app
+// sends nothing and reports nothing back, so what the tutor needs to help with exactly this task goes into lines the
+// learner sends with the click, in the learner's voice: the exercise and its task number, the last wrong input with
+// the tries, the message the app showed for it word for word (so that the tutor starts from what the learner was
+// told, and does not repeat it), the hint or the solution opened, and the page's tutor page with the position
+// (position.ts, taskQuery), which holds the task and the guide (tutorpage.ts). Without a chat (B1) one sentence names
+// the tutor page and the task, as the prompt of a new chat; on a page a tutor opened (via=tutor, B2) the learner
+// pastes the lines into the running chat, the tutor page last. Pure and without Node: the client module calls it.
+import { message } from "./messages.ts";
+import type { TaskState } from "./result.ts";
+
+/** What the lines of one task say. */
+export interface Stuck {
+  /** The exercise's id. */
+  exercise: string;
+  /** The task number, for an exercise with numbers. */
+  number?: number;
+  state: TaskState;
+  /** The page's tutor page with the position, absolute. */
+  tutor: string;
+}
+
+/** The exercise and its task number, in `lang`: "prozentwert-ueben, Nr. 27". */
+const taskOf = (stuck: Stuck, lang: string) => ({
+  exercise: stuck.exercise,
+  number: stuck.number === undefined ? "" : message(lang, "resultNumber", { n: String(stuck.number) }),
+});
+
+/** What the learner did and was told, in `lang`. */
+function stateLines(state: TaskState, lang: string): string[] {
+  const tries =
+    state.attempts === 1 ? message(lang, "resultTry") : message(lang, "resultTries", { n: String(state.attempts) });
+  const lines: string[] = [];
+  if (state.rightAt !== undefined) lines.push(message(lang, "stuckRight", { n: String(state.rightAt) }));
+  else if (state.input !== undefined) lines.push(message(lang, "stuckInput", { input: state.input, tries }));
+  else if (state.attempts > 0) lines.push(message(lang, "stuckTries", { tries }));
+  if (state.rightAt === undefined && state.message !== undefined) {
+    lines.push(message(lang, "stuckMessage", { message: state.message.replace(/\s+/g, " ").trim() }));
+  }
+  if (state.hint === true) lines.push(message(lang, "stuckHint"));
+  if (state.revealed) lines.push(message(lang, "stuckSolution"));
+  return lines;
+}
+
+/** The lines for a running chat (B2), in `lang`: the task, what the learner did and was told, the tutor page. */
+export const stuckLines = (stuck: Stuck, lang: string): string =>
+  [
+    message(lang, "stuckTask", taskOf(stuck, lang)),
+    ...stateLines(stuck.state, lang),
+    `${message(lang, "resultTutor")} ${stuck.tutor}`,
+  ].join("\n");
+
+/** The prompt of a new chat (B1), in `lang`: the tutor page and the task in one sentence, then the lines. */
+export const stuckPrompt = (stuck: Stuck, lang: string): string =>
+  [message(lang, "stuckAsk", { url: stuck.tutor, ...taskOf(stuck, lang) }), ...stateLines(stuck.state, lang)].join(
+    "\n",
+  );