@altnovatrail/spec 0.0.0-stage → 0.4.0

package/formatv0/open/index.d.ts

@@ -0,0 +1,633 @@
+// Code generated by tools/types from format/schemas; DO NOT EDIT.
+
+/**
+ * The open view of each part of a module (format/README.md, section 6): the type of each struct the
+ * open view of a part reaches, by the name it has in formatv0, with the fields marked x-open alone,
+ * of version 0.1. An open view has no check, no template and no solver; a task's has its givens and
+ * its unknown. Strings, integers and enumerations are formatv0's.
+ *
+ * @packageDocumentation
+ */
+
+import type * as formatv0 from "../index.js";
+
+// The open views of the types of manifest.schema.json.
+
+/**
+ * Manifest is the open view of formatv0.Manifest, the type of manifest.schema.json: its fields
+ * marked x-open.
+ *
+ * The manifest of a module, manifest.yaml at the root of its folder: the format version the module
+ * is written in, its ID and version, what it is called and teaches, whom it is for, the bands of
+ * its difficulty scale, its languages, the anchor skills it builds on, the settings of its canvas,
+ * its authors and its license, and the templates of the rungs of its hint ladder. Every field is
+ * open, since the learner's app shows them.
+ */
+export interface Manifest {
+  /**
+   * The version of the module format the module is written in, "0.1": the module is checked, built
+   * and run by it. It stands at the root of the manifest in every version of the format, so that a
+   * reader finds it before it knows which schemas to read the module by.
+   */
+  readonly module_format_version: formatv0.ModuleFormatVersion;
+  /**
+   * The module's ID: novatrail/olympiad-math.
+   */
+  readonly id: formatv0.ModuleID;
+  /**
+   * The module's version, X.Y.Z.
+   */
+  readonly version: formatv0.ModuleVersion;
+  /**
+   * What the module is called, in its explanation language.
+   */
+  readonly title: formatv0.Text;
+  /**
+   * What the module teaches.
+   */
+  readonly subject: formatv0.Subject;
+  /**
+   * Whom the module is for: its age categories and, for a module written for school grades, those
+   * grades.
+   */
+  readonly audience: Audience;
+  /**
+   * The bands of the module's difficulty scale, from the easiest: each task names its band and a
+   * difficulty from 1 to 5 within it. A module with tasks has them.
+   */
+  readonly bands?: readonly Band[];
+  /**
+   * The languages of the module.
+   */
+  readonly languages: Languages;
+  /**
+   * The anchor skills of the shared taxonomy that the module's skills need: exactly those that its
+   * skill graph names as prerequisites. A module whose skills need none leaves this field out.
+   */
+  readonly dependencies?: readonly formatv0.SharedTaxonomy[];
+  /**
+   * The settings of the module's canvas, the same for each of its tasks.
+   */
+  readonly canvas?: CanvasSettings;
+  /**
+   * Who wrote the module.
+   */
+  readonly authors: readonly Author[];
+  /**
+   * The license of the module's content: Apache-2.0 for an official module.
+   */
+  readonly license: formatv0.License;
+  /**
+   * The templates of rungs 1 and 2 of the hint ladder, in order, in the module's explanation
+   * language: what the learner reads after a wrong answer when the tutor's question did not come or
+   * did not pass its checks, and neither a trap text nor a trap's advice fits. A module with an
+   * item with a verdict has them.
+   */
+  readonly rung_templates?: readonly formatv0.Text[];
+}
+
+/**
+ * Audience is the open view of formatv0.Audience, the type of
+ * manifest.schema.json#/properties/audience: its fields marked x-open.
+ *
+ * Whom the module is for: its age categories and, for a module written for school grades, those
+ * grades.
+ */
+export interface Audience {
+  /**
+   * The age categories that the module suits. The platform offers the module only to learners in
+   * one of them.
+   */
+  readonly age_categories: readonly formatv0.AgeCategory[];
+  /**
+   * The school grades that the module is written for. A module that names them asks the learner's
+   * grade, and the answer may be one it does not name. Unlike the age categories, grades close
+   * nothing: the module and its skills stay open to a learner of any grade.
+   */
+  readonly grades?: readonly formatv0.Grade[];
+}
+
+/**
+ * Band is the open view of formatv0.Band, the type of manifest.schema.json#/properties/bands/items:
+ * its fields marked x-open.
+ */
+export interface Band {
+  /**
+   * The band's ID, by which a task names it.
+   */
+  readonly id: formatv0.BandID;
+  /**
+   * What the band is called, in the module's explanation language: Grades 1–2.
+   */
+  readonly title: formatv0.Text;
+  /**
+   * The school grades the band's tasks are written for, in a module that names grades: a learner of
+   * one of them starts in this band.
+   */
+  readonly grades?: readonly formatv0.Grade[];
+}
+
+/**
+ * Languages is the open view of formatv0.Languages, the type of
+ * manifest.schema.json#/properties/languages: its fields marked x-open.
+ *
+ * The languages of the module.
+ */
+export interface Languages {
+  /**
+   * The explanation language: the one language in which the module explains and the tutor speaks
+   * with the learner. Every text of the module is in it, except the material of a language module,
+   * which is in its target language.
+   */
+  readonly explanation: formatv0.LanguageTag;
+  /**
+   * The target language: the one that a language module teaches. Other modules have none.
+   */
+  readonly target?: formatv0.LanguageTag;
+}
+
+/**
+ * CanvasSettings is the open view of formatv0.CanvasSettings, the type of
+ * manifest.schema.json#/properties/canvas: its fields marked x-open.
+ *
+ * The settings of the module's canvas, the same for each of its tasks.
+ */
+export interface CanvasSettings {
+  /**
+   * The height in px that a digit or a letter of the learner's writing has on the crop that goes to
+   * be read: 32 unless given.
+   *
+   * @defaultValue 32
+   */
+  readonly digit_height?: number;
+}
+
+/**
+ * Author is the open view of formatv0.Author, the type of
+ * manifest.schema.json#/properties/authors/items: its fields marked x-open.
+ */
+export interface Author {
+  /**
+   * The name of an author: a person or an organization.
+   */
+  readonly name: formatv0.Text;
+}
+
+// The open views of the types of skill-graph.schema.json.
+
+/**
+ * SkillGraph is the open view of formatv0.SkillGraph, the type of skill-graph.schema.json: its
+ * fields marked x-open.
+ *
+ * The skill graph of a module, skill-graph.yaml at the root of its folder: the module's skills,
+ * what a learner needs before each one, how the platform can know a learner's command of each,
+ * which anchor skills of the shared taxonomy each one teaches, the names of the tiers, and the
+ * skills that the module had once and has no more. The tier of a skill is computed from the
+ * prerequisites, never written, and module-kit puts it into the module's package. Every field is
+ * open but retired_skills, since the skill map shows them.
+ */
+export interface SkillGraph {
+  /**
+   * The names of the tiers, in order from tier 1. The tiers past the last name are shown by their
+   * numbers, and a name past the last tier names none.
+   */
+  readonly tiers?: readonly formatv0.Text[];
+  /**
+   * The module's skills, each under its local ID. Their order carries no meaning.
+   */
+  readonly skills: Readonly<Record<formatv0.SkillID, Skill>>;
+}
+
+/**
+ * Skill is the open view of formatv0.Skill, the type of
+ * skill-graph.schema.json#/properties/skills/additionalProperties: its fields marked x-open.
+ *
+ * A skill of the module, under its local ID.
+ */
+export interface Skill {
+  /**
+   * What the skill is called, in the module's explanation language.
+   */
+  readonly title: formatv0.Text;
+  /**
+   * What a learner who has the skill can do, in the module's explanation language.
+   */
+  readonly description?: formatv0.Text;
+  /**
+   * The skills that a learner needs before this one, all of them: skills of the module by local ID,
+   * and anchor skills of the shared taxonomy by their IDs. A skill with none leaves this field out.
+   */
+  readonly prerequisites?: readonly string[];
+  /**
+   * The anchor skills of the shared taxonomy that this skill teaches: a learner who has this skill
+   * can do what the description of each says. Other modules build on them, and the learner model
+   * decides by such skills whether a learner has them. A skill that teaches none leaves this field
+   * out.
+   */
+  readonly teaches?: readonly formatv0.SharedTaxonomy[];
+  /**
+   * How the platform can know a learner's command of the skill: verdict, when its tasks are checked
+   * against a key or a predicate; rubric, when work on it gets feedback by the author's rubric and
+   * no verdict; none, when it is practised and not assessed.
+   */
+  readonly assessability: formatv0.SkillAssessability;
+}
+
+// The open views of the types of traps.schema.json.
+
+/**
+ * Traps is the open view of formatv0.Traps, the type of traps.schema.json: its fields marked
+ * x-open.
+ *
+ * The trap catalog of a module, traps.yaml at the root of its folder: the typical mistakes that the
+ * module's tasks catch, each under its local ID, with what the mistake is, the skills it belongs to
+ * and what to advise on it. A task names only a trap of the catalog, so that a wrong answer becomes
+ * a diagnosis that can be counted. Every field is closed, since a trap tells what mistake a task
+ * expects.
+ */
+export type Traps = { readonly [field: string]: never };
+
+// The open views of the types of techniques.schema.json.
+
+/**
+ * Techniques is the open view of formatv0.Techniques, the type of techniques.schema.json: its
+ * fields marked x-open.
+ *
+ * The technique catalog of a module, techniques.yaml at the root of its folder: the ways of solving
+ * that the module names and teaches, each under its local ID, with its title and what it is. A task
+ * names the techniques that help in it, and which those are is closed, in the task. Every field of
+ * the catalog is open, as the skills of the skill graph are.
+ */
+export interface Techniques {
+  /**
+   * The module's techniques, each under its local ID. Their order carries no meaning, and this
+   * version gives them no numbers.
+   */
+  readonly techniques: Readonly<Record<formatv0.TechniqueID, Technique>>;
+}
+
+/**
+ * Technique is the open view of formatv0.Technique, the type of
+ * techniques.schema.json#/properties/techniques/additionalProperties: its fields marked x-open.
+ *
+ * A technique of the module, under its local ID.
+ */
+export interface Technique {
+  /**
+   * What the technique is called, in the module's explanation language.
+   */
+  readonly title: formatv0.Text;
+  /**
+   * What the technique is and when it helps, in the module's explanation language.
+   */
+  readonly description?: formatv0.Text;
+}
+
+// The open views of the types of solving-steps.schema.json.
+
+/**
+ * SolvingSteps is the open view of formatv0.SolvingSteps, the type of solving-steps.schema.json:
+ * its fields marked x-open.
+ *
+ * The solving steps of a module, solving-steps.yaml at the root of its folder: the frame through
+ * which the tutor leads a learner within a task, step by step, each with its title, what of the
+ * task it gives and when it ends. Every task of the module goes through the same steps. Every field
+ * is open, since the learner's app leads the steps itself.
+ */
+export interface SolvingSteps {
+  /**
+   * The steps, in order, each named by its place, from 1.
+   */
+  readonly steps: readonly Step[];
+}
+
+/**
+ * Step is the open view of formatv0.Step, the type of solving-steps.schema.json#/$defs/step: its
+ * fields marked x-open.
+ *
+ * A solving step: what the learner does in it, what of the task it gives, and when it ends.
+ */
+export interface Step {
+  /**
+   * What the learner does in the step, in the module's explanation language.
+   */
+  readonly title: formatv0.Text;
+  /**
+   * What of the task the step gives the learner: givens, the task's givens and unknown, which the
+   * learner ticks; techniques, the task's techniques, which the server gives when the step begins.
+   * A step that gives neither leaves this field out.
+   */
+  readonly gives?: readonly formatv0.StepGives[];
+  /**
+   * When the step ends, by an event on the learner's device and with no key: givens_ticked, once
+   * the learner has ticked every given and the unknown; answer_slots_filled, once every answer slot
+   * of the task holds something of the learner's; none, when the learner moves on.
+   */
+  readonly exit_condition: formatv0.StepExitCondition;
+}
+
+// The open views of the types of task.schema.json.
+
+/**
+ * Task is the open view of formatv0.Task, the type of task.schema.json: its fields marked x-open.
+ *
+ * A task of a module, tasks/<id>.yaml in its folder: its statement, its canvas, its items with
+ * their answer slots, each with the check that says what is right in it, the skills it trains, its
+ * band and difficulty, and, when they are fewer than the module's, the age categories it is for;
+ * and what helps the learner on the way: what the statement gives and asks, the techniques that
+ * help, the traps that AI may suggest, a simpler case for each item, the solution and the phrases
+ * that give the answer away. The ID, the statement, the canvas, the items, the givens and the
+ * unknown are open, since the learner's app shows them, but for the skills and the simpler case of
+ * an item and the check of each answer slot; those, the skills, the band, the difficulty, the age
+ * categories, the techniques, the traps, the solution, the leak phrases and the template are
+ * closed, since the server reads them. A task with a template is a template of tasks: each attempt
+ * gets one instance of it, with numbers in the place of its placeholders.
+ */
+export interface Task {
+  /**
+   * The task's local ID: the name of its file, without .yaml.
+   */
+  readonly id: formatv0.TaskID;
+  /**
+   * The statement of the task, what the learner reads: paragraphs and pictures in order, in the
+   * module's explanation language. Whether it stands above the canvas or on it is the canvas kind's
+   * to decide.
+   */
+  readonly statement: readonly StatementPart[];
+  /**
+   * The canvas of the task, one for all its items: its kind and the kind's settings.
+   */
+  readonly canvas: Canvas;
+  /**
+   * The items of the task, each named by its place, from 1. On a handwriting sheet an item has
+   * answer slots; on a workbook it is a line of text and boxes.
+   */
+  readonly items: readonly Item[];
+  /**
+   * What the statement gives, each a short text in the module's explanation language: the chips
+   * that the learner ticks at a solving step that gives them, and what a hint asked for gives
+   * before the first answer.
+   */
+  readonly givens?: readonly formatv0.Text[];
+  /**
+   * What the task asks to find, in the module's explanation language: the chip that the learner
+   * ticks beside the givens.
+   */
+  readonly unknown?: formatv0.Text;
+}
+
+/**
+ * Item is the open view of formatv0.Item, the type of task.schema.json#/$defs/item: its fields
+ * marked x-open.
+ *
+ * An item of the task: on a handwriting sheet, its answer slots and what it asks; on a workbook, a
+ * line of text and boxes.
+ */
+export interface Item {
+  /**
+   * What the item asks, on a handwriting sheet, beside its answer slots: a) or a question.
+   */
+  readonly text?: formatv0.Text;
+  /**
+   * The answer slots of an item on a handwriting sheet, each named by its place in the item, from
+   * 1.
+   */
+  readonly answer_slots?: readonly AnswerSlot[];
+  /**
+   * An item of a workbook: pieces of text and boxes in order, as 7 × [ ] = 56, and at least one
+   * box. Its boxes are its answer slots, each named by its place among them, from 1.
+   */
+  readonly line?: readonly LinePart[];
+}
+
+/**
+ * AnswerSlot is the open view of formatv0.AnswerSlot, the type of
+ * task.schema.json#/$defs/answer_slot: its fields marked x-open.
+ *
+ * An answer slot of an item on a handwriting sheet: its binding, the zone or the options that the
+ * binding needs, and its check.
+ */
+export interface AnswerSlot {
+  /**
+   * Where and how the learner gives the answer on a handwriting sheet: anywhere on it, where AI
+   * finds the final answer; the whole sheet, a work as a whole, such as an essay; in a zone of it;
+   * or by choosing one of the options.
+   */
+  readonly binding: formatv0.AnswerSlotBinding;
+  /**
+   * The zone of the sheet where the learner writes the answer.
+   */
+  readonly zone?: SheetRectangle;
+  /**
+   * The options the learner chooses from, in the order they are shown.
+   */
+  readonly options?: readonly formatv0.Text[];
+}
+
+/**
+ * LinePart is the open view of formatv0.LinePart, the type of task.schema.json#/$defs/line_part:
+ * its fields marked x-open.
+ *
+ * A piece of a line: a piece of text, or a box with its check.
+ */
+export interface LinePart {
+  /**
+   * A piece of the line's text.
+   */
+  readonly text?: formatv0.Text;
+  /**
+   * A box of the line, an answer slot where the learner writes the answer.
+   */
+  readonly binding?: formatv0.LinePartBinding;
+}
+
+// The open views of the types of common.schema.json.
+
+/**
+ * StatementPart is the open view of formatv0.StatementPart, the type of
+ * common.schema.json#/$defs/statement_part: its fields marked x-open.
+ *
+ * A part of a text that the learner reads — a statement, a solution or an explanation: a paragraph,
+ * or a picture with what it shows and its size.
+ */
+export interface StatementPart {
+  /**
+   * A paragraph, as plain text.
+   */
+  readonly text?: formatv0.Text;
+  /**
+   * A picture, by its path from media/.
+   */
+  readonly picture?: formatv0.PicturePath;
+  /**
+   * What the picture shows, in words: a screen reader reads it, and it stands in the picture's
+   * place until the picture comes. Empty for a picture that only decorates.
+   */
+  readonly alt?: string;
+  /**
+   * The width the picture is shown at, in CSS px; narrower when the text it stands in is.
+   */
+  readonly width?: number;
+  /**
+   * The height the picture is shown at, in CSS px, in proportion to its width.
+   */
+  readonly height?: number;
+}
+
+/**
+ * Canvas is the open view of formatv0.Canvas, the type of common.schema.json#/$defs/canvas: its
+ * fields marked x-open.
+ *
+ * A canvas: its kind, and the grid of a handwriting sheet.
+ */
+export interface Canvas {
+  /**
+   * The canvas kind: a handwriting sheet, a free sheet of 1000 × 1400 units; or a workbook, lines
+   * of items with boxes for the answers.
+   */
+  readonly kind: formatv0.CanvasKind;
+  /**
+   * The grid of a handwriting sheet: squares, lines or dots; squares unless given.
+   *
+   * @defaultValue "squares"
+   */
+  readonly grid?: formatv0.CanvasGrid;
+  /**
+   * The step of the grid of a handwriting sheet, in its units: 50 unless given.
+   *
+   * @defaultValue 50
+   */
+  readonly grid_step?: number;
+}
+
+/**
+ * SheetRectangle is the open view of formatv0.SheetRectangle, the type of
+ * common.schema.json#/$defs/sheet_rectangle: its fields marked x-open.
+ *
+ * A rectangle of the handwriting sheet, in its units of 1000 × 1400 from the top left corner.
+ */
+export interface SheetRectangle {
+  /**
+   * How far the rectangle begins from the left edge of the sheet, in its units.
+   */
+  readonly left: number;
+  /**
+   * How far the rectangle begins from the top edge of the sheet, in its units.
+   */
+  readonly top: number;
+  /**
+   * The width of the rectangle, in units of the sheet.
+   */
+  readonly width: number;
+  /**
+   * The height of the rectangle, in units of the sheet.
+   */
+  readonly height: number;
+}
+
+// The open views of the types of lesson.schema.json.
+
+/**
+ * Lesson is the open view of formatv0.Lesson, the type of lesson.schema.json: its fields marked
+ * x-open.
+ *
+ * A lesson of a module: a sequence that its author made — explanations, worked examples and tasks,
+ * in order — and the skills of the module that it teaches. The skill graph orders the lessons.
+ */
+export interface Lesson {
+  /**
+   * The lesson's local ID: the name of its file, without .yaml.
+   */
+  readonly id: formatv0.LessonID;
+  /**
+   * What the lesson is called, in the module's explanation language. The learner sees it before
+   * every task of the lesson, and the leak check searches it for their keys.
+   */
+  readonly title: formatv0.Text;
+  /**
+   * The segments of the lesson, in the author's order: explanations, worked examples and tasks. No
+   * two are the same.
+   */
+  readonly segments: readonly Segment[];
+}
+
+/**
+ * Segment is the open view of formatv0.Segment, the type of lesson.schema.json#/$defs/segment: its
+ * fields marked x-open.
+ *
+ * A segment of a lesson: an explanation, a worked example or a task, by its one field.
+ */
+export interface Segment {
+  /**
+   * An explanation: paragraphs and pictures that the learner reads, in order, in the module's
+   * explanation language.
+   */
+  readonly explanation?: readonly StatementPart[];
+  /**
+   * A worked example: an example solved before the learner's eyes, on a handwriting sheet.
+   */
+  readonly worked_example?: WorkedExample;
+  /**
+   * A task of the module, by its local ID. The next segment begins when the task ends.
+   */
+  readonly task?: formatv0.TaskID;
+}
+
+/**
+ * WorkedExample is the open view of formatv0.WorkedExample, the type of
+ * lesson.schema.json#/$defs/worked_example: its fields marked x-open.
+ *
+ * A worked example of a lesson: no task, with no answer slots and no key.
+ */
+export interface WorkedExample {
+  /**
+   * What the example asks: paragraphs and pictures in order, as a task's statement.
+   */
+  readonly statement: readonly StatementPart[];
+  /**
+   * The sheet that the author's demo is shown on: a handwriting sheet and its grid. The learner
+   * does not write on it.
+   */
+  readonly canvas: Canvas;
+  /**
+   * The author's demo: the parts of how the example is solved, in order, which the learner opens
+   * one at a time and may hide.
+   */
+  readonly demo: readonly DemoPart[];
+}
+
+/**
+ * DemoPart is the open view of formatv0.DemoPart, the type of lesson.schema.json#/$defs/demo_part:
+ * its fields marked x-open.
+ *
+ * A part of the author's demo: a paragraph; a picture beside the sheet, with what it shows and its
+ * size; or a picture on the sheet, with what it shows and its area.
+ */
+export interface DemoPart {
+  /**
+   * A paragraph of the demo, as plain text.
+   */
+  readonly text?: formatv0.Text;
+  /**
+   * A picture of the demo, by its path from media/.
+   */
+  readonly picture?: formatv0.PicturePath;
+  /**
+   * What the picture shows, in words: a screen reader reads it, and it stands in the picture's
+   * place until the picture comes. Empty for a picture that only decorates.
+   */
+  readonly alt?: string;
+  /**
+   * The width that a picture beside the sheet is shown at, in CSS px.
+   */
+  readonly width?: number;
+  /**
+   * The height that a picture beside the sheet is shown at, in CSS px, in proportion to its width.
+   */
+  readonly height?: number;
+  /**
+   * The area of the sheet that a picture on the sheet is shown in, at its size, on the canvas layer
+   * of the author's demo.
+   */
+  readonly area?: SheetRectangle;
+}

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@altnovatrail/spec",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "The types of NovaTrail's module format for TypeScript, generated from its schemas: the parts of a module and their open views, the canonical view, the inventory, the module index and the test vectors.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/altnovatrail/spec.git"
+  },
+  "type": "module",
+  "exports": {
+    "./formatv0": {
+      "types": "./formatv0/index.d.ts"
+    },
+    "./formatv0/open": {
+      "types": "./formatv0/open/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "formatv0"
+  ],
+  "sideEffects": false
+}