@lernapps/app-templates 0.0.1 → 0.1.1

package/runtime/explainer/content.ts

@@ -0,0 +1,277 @@
+// The content of an explainer, as the YAML files in src/ give it (explainer.v1.schema.json) and the build reads it
+// (load.ts): the app, its chapters in order, their pages in order, the data files, the bundled images and the
+// components (src/components/, components.ts) with the blocks that use them.
+
+import type { Question } from "../shared/questions/question.ts";
+import type { DataRecord, Generated } from "./generated/types.ts";
+import type { Credit, Drawing, MaterialBlock } from "../shared/blocks/block.ts";
+import { inLanguage, type Text } from "../shared/languages.ts";
+
+export type { Credit, Drawing };
+
+export { inLanguage, type Text };
+
+/** An exercise of one of the question types, with the fields of a question; its texts may be maps by language. */
+export type QuestionBlock = Question<Text>;
+/** A point of a good answer to an open task: about the content, with its source, or about the form. */
+export interface OpenTaskPoint {
+  text: Text;
+  kind?: "content" | "form";
+  /** Where its content is: /<chapter>/<page>/#<section>. */
+  source?: string;
+}
+
+/** An open task: answered in the learner's own words, then compared with the points of a good answer. */
+export interface OpenTask {
+  type: "open-task";
+  id: string;
+  task: Text;
+  /** How the learner may answer; both when not given. */
+  answer?: readonly ("text" | "photo")[];
+  points: readonly OpenTaskPoint[];
+  /** The model answer. */
+  solution: Text;
+  hint?: Text;
+}
+
+/** An exercise block: one of the question types, generated, or an open task. */
+export type Exercise = QuestionBlock | Generated | OpenTask;
+
+export interface Source {
+  title: Text;
+  url?: string;
+}
+
+export interface App {
+  title: Text;
+  intro: Text;
+  languages: readonly string[];
+  chapters: readonly string[];
+  sources?: readonly Source[];
+  /** What the app adds for a KI tutor: its own rules (restricted Markdown), after the guide of each tutor page. */
+  tutor?: {
+    rules?: Text;
+  };
+  /** The scope for the tutor: what the app is about, and what does not belong to it (scope.ts). */
+  scope?: {
+    text?: Text;
+    out: readonly Text[];
+  };
+}
+
+/**
+ * A self-assessment (assessment.ts): its pages in order, each with its exercises, each as /<chapter>/<page>/#<exercise>.
+ */
+export interface SelfAssessment {
+  pages: readonly { exercises: readonly string[] }[];
+}
+
+export interface Event {
+  date: number | string;
+  label?: Text;
+  title: Text;
+  text?: Text;
+}
+
+export type Block =
+  | MaterialBlock<Text>
+  | { type: "timeline"; events?: readonly Event[]; data?: string }
+  | { type: "definition"; term: Text; explanation: Text }
+  /** A YouTube video behind two clicks (video.ts): its id, and its title and channel as YouTube names them. */
+  | { type: "video"; youtube: string; title: string; channel: string }
+  | { type: "example" | "note"; title: Text; blocks: readonly Block[] }
+  | { type: "section"; id: string; title: Text; blocks: readonly Block[] }
+  | {
+      type: "vue-component";
+      /** Its anchor; an exercise component without one has its name in kebab case (assign-labels). */
+      id?: string;
+      component: string;
+      props?: Readonly<Record<string, unknown>>;
+      /** Required for a component that is no exercise; an exercise component's no-JS text is generated from describe. */
+      nojs?: Text;
+      examples?: ComponentExamples;
+    }
+  | Exercise;
+
+export type BlockOf<T extends Block["type"]> = Extract<Block, { type: T }>;
+
+export interface Page {
+  id: string;
+  chapter: string;
+  /** The source file, from the app's root: src/<chapter>/<page>.yaml. */
+  file: string;
+  title: Text;
+  description?: Text;
+  /** What the page teaches, for the tutor's scope (scope.ts). */
+  scope?: Text;
+  blocks: readonly Block[];
+}
+
+export interface Chapter {
+  id: string;
+  title: Text;
+  summary?: Text;
+  pages: readonly Page[];
+  /** A self-assessment over the exercises of this chapter (assessment.ts). */
+  selfAssessment?: SelfAssessment;
+  /** What the chapter is about, for the tutor's scope. */
+  scope?: Text;
+}
+
+export type { DataRecord };
+
+export interface Site {
+  app: App;
+  chapters: readonly Chapter[];
+  /** The records of each data file src/data/<name>.yaml, by name. */
+  data: Readonly<Record<string, readonly DataRecord[]>>;
+  /** The bundled images that blocks use, by their path from src/ (images/<name>), with the file's absolute path. */
+  images: ReadonlyMap<string, string>;
+  /** Each vue-component block, with its component and where it is. */
+  components: readonly ComponentUse[];
+  /** The app's name for what it keeps on the device (its package.json name; @lernapps/tooling/storage). */
+  storage?: string;
+}
+
+// What the build reads of a component (components.ts). Declared here, not there: the client module reaches this file,
+// and components.ts is build code that needs Node.
+
+/** A prop type that a block's props can give. */
+export type PropType =
+  | { kind: "string" | "number" | "boolean" | "unknown" }
+  | { kind: "literal"; values: readonly (string | number | boolean)[] }
+  | { kind: "array"; of: PropType }
+  | { kind: "object"; fields: Readonly<Record<string, Field>> }
+  | { kind: "union"; of: readonly PropType[] };
+
+export interface Field {
+  type: PropType;
+  optional: boolean;
+  /** The declaration as written, e.g. "parts: string[]". */
+  source: string;
+}
+
+export interface ComponentInfo {
+  name: string;
+  /** src/components/<Name>.vue */
+  file: string;
+  /** The .vue file's absolute path. */
+  path: string;
+  /** The props a block gives: every declared prop but seed, which the explainer gives an exercise component. */
+  props: Readonly<Record<string, Field>>;
+  /** Whether it emits answer: an exercise, which gets the seed of its task number as the prop seed. */
+  exercise: boolean;
+  /** Whether it declares the prop checked, which the explainer sets once it checked the answer the component has. */
+  checked: boolean;
+  /** Whether it keeps its nojs text, folded as a text description, once it runs, rather than replacing it. */
+  caption: boolean;
+  /** The absolute path of its logic module <Name>.ts, for an exercise. */
+  logic?: string;
+}
+
+/** An example of an exercise component: the answer its check takes, for the task of `seed`, or of every seed. */
+export interface ComponentExample {
+  answer: unknown;
+  seed?: number;
+}
+
+/** The examples of an exercise component's block: test cases for the build, never shown to learners. */
+export interface ComponentExamples {
+  accepted?: readonly ComponentExample[];
+  rejected?: readonly ComponentExample[];
+}
+
+/** A vue-component block of a page, with the component it uses. */
+export interface ComponentUse {
+  block: BlockOf<"vue-component">;
+  component: ComponentInfo;
+  /** Its anchor on the page, for an exercise component or a block with an id: the block's id or the default. */
+  id?: string;
+  /** Where the block is, as a problem line starts: src/<chapter>/<page>.yaml:<line>: blocks[0].blocks[3] */
+  place: string;
+  /** Where each of its examples is, as a problem line starts, by kind. */
+  examples: { accepted: string[]; rejected: string[] };
+}
+
+/** The events of a timeline: its own, or the records of its data file. */
+export function timelineEvents(site: Site, block: BlockOf<"timeline">): readonly Event[] {
+  if (block.events !== undefined) return block.events;
+  return (site.data[block.data ?? ""] ?? []) as unknown as readonly Event[];
+}
+
+/**
+ * What an exercise component says about itself (the export about of its logic module), for a tutor: what the learner
+ * does, the answer's format, what counts as right, and the typical mistakes. Each a text, a map by language when the
+ * app has more than one.
+ */
+export interface ComponentAbout {
+  task: Text;
+  answer: Text;
+  correct: Text;
+  mistakes: readonly Text[];
+}
+
+/** A task of an exercise component, as its describe(task, props, lang) states it: restricted Markdown each. */
+export interface DescribedTask {
+  /** Its task number, from 1. */
+  number: number;
+  seed: number;
+  task: string;
+  solution: string;
+}
+
+/**
+ * An exercise component as a tutor reads it, in one language, from the exports template, params, mistakes and show
+ * of its logic: the task once with a placeholder for each input, and each task number's inputs and outputs, as a
+ * generated exercise has them (its typical mistakes are those of about).
+ */
+export interface ComponentExercise {
+  /** The task as a learner reads it, with {name} for each input, on one line: template(props, lang). */
+  template: string;
+  /** The names of the inputs in order, the columns before the solution: the keys of params(task, props, lang). */
+  inputs: readonly string[];
+  /** Each task number's task, from 1: the values of its inputs, its solution and what each typical mistake gives ("" for none), as text. */
+  tasks: readonly { inputs: readonly string[]; solution: string; mistakes: readonly string[] }[];
+}
+
+/** What the build learnt from an exercise component's logic for one block: its about, and its tasks by language. */
+export interface ComponentDescription {
+  about: ComponentAbout;
+  /** The seed of each task number, from 1: the seeds of its distinct tasks (distinctSeeds of tasks.ts). */
+  seeds: readonly number[];
+  /** The task of each number, in each language. */
+  tasks: Readonly<Record<string, readonly DescribedTask[]>>;
+  /** The exercise in each language, when its logic declares its inputs and outputs; else none. */
+  exercise?: Readonly<Record<string, ComponentExercise>>;
+}
+
+/** Every block of `blocks`, depth first, with the blocks inside sections and boxes. */
+export function* allBlocks(blocks: readonly Block[]): Generator<Block> {
+  for (const block of blocks) {
+    yield block;
+    if (block.type === "section" || block.type === "example" || block.type === "note") yield* allBlocks(block.blocks);
+  }
+}
+
+/** Whether a block is an exercise. */
+export const isExercise = (block: Block): block is Exercise =>
+  block.type === "generated" ||
+  block.type === "open-task" ||
+  ["single-choice", "multiple-choice", "true-false", "number", "ordering", "matching"].includes(block.type);
+
+/** The anchor of a term in the glossary: the German term in lower case, umlauts spelled out, hyphens for the rest. */
+export function termId(term: Text): string {
+  return inLanguage(term, "de")
+    .toLowerCase()
+    .replace(/ä/g, "ae")
+    .replace(/ö/g, "oe")
+    .replace(/ü/g, "ue")
+    .replace(/ß/g, "ss")
+    .normalize("NFD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+/** What the logic of each exercise component's block describes (plugin.ts): its about, and its tasks by language. */
+export type Descriptions = ReadonlyMap<Block, ComponentDescription>;