@lernapps/app-templates 0.0.1 → 0.1.1

package/runtime/shared/questions/question.v1.schema.json

@@ -0,0 +1,346 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:lernapps:schema:question.v1",
+  "title": "A question of a lernapps app",
+  "description": "One question of the six types (single-choice, multiple-choice, true-false, number, ordering, matching) as the quiz's question bank and the explainer's exercises write it. Use #/$defs/question for one question; the schemas of the quiz and of the explainer refer to it.",
+  "$defs": {
+    "question": {
+      "type": "object",
+      "required": ["id", "type", "text", "explanation", "links"],
+      "properties": {
+        "id": {
+          "description": "Stable name of the question, used in its address (#frage-<id>): lower-case letters, digits and hyphens. Keep it when the text changes, so links to the question keep working.",
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "type": {
+          "description": "The kind of question.",
+          "enum": ["single-choice", "multiple-choice", "true-false", "number", "ordering", "matching"]
+        },
+        "text": {
+          "description": "The question, complete in itself.",
+          "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+        },
+        "material": {
+          "description": "Optional: content that the question shows, between its text and its answers: prose, formulas, figures and labelled figures (bundled images in src/images/, or drawn from data), tables, quotations and code. A figure has an alternative text and a caption, and an image its source and licence. A question that asks about what the content shows needs it; one that merely looks nicer with an image should not have one.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "urn:lernapps:schema:blocks.v1#/$defs/materialBlock"
+          }
+        },
+        "explanation": {
+          "description": "Why the right answer is right, in one to three sentences. For number, ordering and matching questions also the background knowledge, as their options carry none.",
+          "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+        },
+        "links": {
+          "description": "Further reading on the question, at least one link, e.g. to the article in the German Wikipedia; in a quiz or on a page in several languages to the article in each language's Wikipedia, with url as a map by language.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/link"
+          }
+        },
+        "hint": {
+          "description": "Optional: what to look at again after a wrong answer, in one sentence, without giving the answer away, e.g. \"Schau dir noch einmal an, wie hoch die Spannung im Haushalt ist.\" Shown with the feedback of a wrong answer when nothing more specific applies: a chosen option's info or a number's typical mistake come first. In an explainer, a wrong answer can be tried again, with this hint, before the solution shows.",
+          "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+        },
+        "examples": {
+          "$ref": "#/$defs/examples"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "const": "single-choice"
+              }
+            },
+            "required": ["type"]
+          },
+          "then": {
+            "$ref": "#/$defs/choice"
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "const": "multiple-choice"
+              }
+            },
+            "required": ["type"]
+          },
+          "then": {
+            "$ref": "#/$defs/choice"
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "const": "true-false"
+              }
+            },
+            "required": ["type"]
+          },
+          "then": {
+            "$ref": "#/$defs/trueFalse"
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "const": "number"
+              }
+            },
+            "required": ["type"]
+          },
+          "then": {
+            "$ref": "#/$defs/number"
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "const": "ordering"
+              }
+            },
+            "required": ["type"]
+          },
+          "then": {
+            "$ref": "#/$defs/ordering"
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "const": "matching"
+              }
+            },
+            "required": ["type"]
+          },
+          "then": {
+            "$ref": "#/$defs/matching"
+          }
+        }
+      ],
+      "unevaluatedProperties": false
+    },
+    "examples": {
+      "description": "Optional: test cases for the build, never shown to learners. Before you write the question, note which answers fulfil its text and which typical wrong answers there are; write the other correct answers the text allows (also those other than the one you marked) into accepted, the typical wrong ones into rejected. The build runs each through the same check the page uses and fails when it accepts a rejected answer or rejects an accepted one: then the question checks something other than what its text asks (e.g. an ordering whose text says the order does not matter), so change the question or its text. An answer as the learner gives it, by the type: single-choice an option; multiple-choice a list of options, e.g. [0, 2]; true-false true or false; number a number, or the text as a learner types it, e.g. \"12,5\"; ordering every item in the learner's order; matching a list of pairs [left, right], one for each left entry. An option, item or entry is its index from 0 in the order written, or its text as written (in German). A number's mistakes and the info of wrong options already count as rejected.",
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "accepted": {
+          "description": "Answers the text allows, each of which the check must accept.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/exampleAnswer"
+          }
+        },
+        "rejected": {
+          "description": "Typical wrong answers, each of which the check must reject.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/exampleAnswer"
+          }
+        }
+      }
+    },
+    "exampleAnswer": {
+      "description": "An answer as the learner gives it, in the shape of the question's type (see examples); the build checks its shape."
+    },
+    "choice": {
+      "type": "object",
+      "description": "Single choice: exactly one option is correct. Multiple choice: at least one option is correct, and the learner selects every correct one.",
+      "required": ["options"],
+      "properties": {
+        "options": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 8,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["text", "correct", "info"],
+            "properties": {
+              "text": {
+                "description": "The option as the learner reads it.",
+                "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+              },
+              "correct": {
+                "description": "Whether this option is correct.",
+                "type": "boolean"
+              },
+              "info": {
+                "description": "One to three sentences of background on this option itself, true whether or not it is the right answer, e.g. \"Der Uluru ist ein Inselberg in der Wüste Zentralaustraliens ...\". After an answer it shows for every option. For a wrong option it is also the reason a learner who chose it reads with the feedback, so say there why it does not fit.",
+                "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+              },
+              "alt": {
+                "description": "Optional: the option as it is spoken, for the name of its radio button or checkbox, when its text is only a formula, e.g. \"zwei hoch sieben\" for \"$2^7$\". Without it the name is made from the formula in the page's language (\"2 hoch 7\"); write it where that reads badly, e.g. for a chemical formula. Not needed when the text has words.",
+                "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+              },
+              "link": {
+                "description": "Further reading on this option.",
+                "$ref": "#/$defs/link"
+              }
+            }
+          }
+        }
+      }
+    },
+    "trueFalse": {
+      "type": "object",
+      "description": "A statement the learner judges as true or false; the background goes into the explanation.",
+      "required": ["answer"],
+      "properties": {
+        "answer": {
+          "description": "Whether the statement is true.",
+          "type": "boolean"
+        }
+      }
+    },
+    "number": {
+      "type": "object",
+      "description": "The learner types a number; it counts when it is within the tolerance of the answer. A comma or a point both work as the decimal sign. The background goes into the explanation.",
+      "required": ["answer", "tolerance"],
+      "properties": {
+        "answer": {
+          "description": "The right number.",
+          "type": "number"
+        },
+        "tolerance": {
+          "description": "How far the learner's number may be from the answer and still count; 0 for an exact answer. Match it to the rounding the question asks for.",
+          "type": "number",
+          "minimum": 0
+        },
+        "unit": {
+          "description": "The unit, shown next to the input, e.g. \"cm\"; the learner does not type it.",
+          "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+        },
+        "mistakes": {
+          "description": "Optional: typical wrong numbers, each with a message that says what went wrong, e.g. { \"answer\": 2300, \"message\": \"Du hast mit 10 statt mit 100 multipliziert.\" }. A learner's number within the tolerance of a mistake's answer gets its message with the feedback. A mistake's answer must not count as right, and each is listed once.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["answer", "message"],
+            "properties": {
+              "answer": {
+                "description": "The wrong number, as the mistake gives it.",
+                "type": "number"
+              },
+              "message": {
+                "description": "What went wrong, in one or two sentences, without giving the right number away.",
+                "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+              }
+            }
+          }
+        }
+      }
+    },
+    "ordering": {
+      "type": "object",
+      "description": "The learner puts the items in order, e.g. by height. Write them in the right order: the page shows them mixed. The background goes into the explanation.",
+      "required": ["items"],
+      "properties": {
+        "items": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 8,
+          "items": {
+            "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+          }
+        }
+      }
+    },
+    "matching": {
+      "type": "object",
+      "description": "The learner matches each left entry with its right entry. Write the pairs as they belong together: the page shows the right entries mixed. The background goes into the explanation. Instead of the pairs, a question about a figure to label takes them from the figure (pairsFrom).",
+      "properties": {
+        "pairsFrom": {
+          "description": "material: the pairs are the labels of the labelled figure in the material, each marker (A, B, 1) on the left with its text on the right, so that they are written once. The figure must have legend: false, as its legend would give the answers away; the solution lists them. Write either the pairs or pairsFrom.",
+          "const": "material"
+        },
+        "distractors": {
+          "description": "Optional: right entries that match none of the left entries, wrong answers the learner may choose, shown mixed with the right entries. Use them for plausible mistakes, or for entries that have nothing to do with the task; 1 to 4 of them.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 4,
+          "items": {
+            "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+          }
+        },
+        "pairs": {
+          "description": "The pairs, written out. Without pairsFrom they are required.",
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 8,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["left", "right"],
+            "properties": {
+              "left": {
+                "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+              },
+              "right": {
+                "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+              }
+            }
+          }
+        }
+      }
+    },
+    "link": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title", "url"],
+      "properties": {
+        "title": {
+          "description": "The link's text: what the learner finds there, e.g. \"Uluru (Wikipedia)\".",
+          "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+        },
+        "url": {
+          "description": "The address, https only: one for every language, or, in a quiz or on a page in several languages where the page to read differs by language (the article in each language's Wikipedia), a map of addresses by language ({ \"de\": \"https://de.wikipedia.org/wiki/Uluru\", \"en\": \"https://en.wikipedia.org/wiki/Uluru\" }) with every declared language, as a text's map. Each language's page links the address of its language. Check that each opens the page you mean.",
+          "$ref": "#/$defs/address"
+        }
+      }
+    },
+    "address": {
+      "description": "An address, https only: a string, the same in every language, or a map of addresses by language ({ de: …, en: … }) in a quiz or on a page in several languages. The quiz or page checks that a map has every language it declares, and no other.",
+      "anyOf": [
+        {
+          "type": "string",
+          "pattern": "^https://[^\\s]+$"
+        },
+        {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": {
+            "pattern": "^[a-z]{2}$"
+          },
+          "additionalProperties": {
+            "type": "string",
+            "pattern": "^https://[^\\s]+$"
+          }
+        }
+      ]
+    }
+  }
+}

package/runtime/shared/questions/questions.css

@@ -0,0 +1,192 @@
+/* The look of a question, for every archetype that has questions; the stylesheets of the quiz and of the explainer
+   import it. Its fieldset, its controls, the button to check it, its feedback and the background of its options, in the
+   colours of the page (page.css). */
+
+.question {
+  margin: 0 0 1.5rem;
+}
+
+.question fieldset {
+  margin: 0;
+  padding: 0.75rem 1rem;
+  border: 1px solid var(--page-border);
+  border-radius: 0.5rem;
+  background: var(--page-surface);
+  min-width: 0;
+}
+
+.question legend {
+  padding: 0 0.25rem;
+  font-weight: 600;
+}
+
+.question-material {
+  margin: 0.75rem 0;
+}
+
+.question-material > :first-child {
+  margin-top: 0;
+}
+
+.question-material > :last-child {
+  margin-bottom: 0;
+}
+
+.question-option {
+  display: flex;
+  gap: 0.5rem;
+  align-items: flex-start;
+  padding: 0.375rem 0;
+}
+
+.question-option input {
+  margin-top: 0.3rem;
+  flex: none;
+}
+
+.question-number input,
+.question-pairs select {
+  font: inherit;
+  padding: 0.25rem 0.5rem;
+  border: 1px solid var(--page-border);
+  border-radius: 0.25rem;
+  background: var(--page-background);
+  color: var(--page-text);
+  max-width: 100%;
+}
+
+.question-number input {
+  width: 8rem;
+}
+
+.question-pairs {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.question-pairs li {
+  padding: 0.375rem 0;
+}
+
+.question-pairs label {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  align-items: center;
+}
+
+.question-hint {
+  margin: 0 0 0.5rem;
+  color: var(--page-muted);
+}
+
+.question-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.question-feedback:not(:empty) {
+  margin: 0.75rem 0;
+  padding: 0.5rem 1rem;
+  border-radius: 0.375rem;
+  border: 1px solid var(--page-border);
+}
+
+.question-feedback p {
+  margin: 0.25rem 0;
+}
+
+.question-right {
+  background: var(--page-right-background);
+  color: var(--page-right);
+}
+
+.question-wrong {
+  background: var(--page-wrong-background);
+  color: var(--page-wrong);
+}
+
+.question-infos,
+.question-links {
+  padding-left: 0;
+  list-style: none;
+}
+
+.question-info {
+  margin: 0.5rem 0;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--page-border);
+  border-left-width: 4px;
+  border-radius: 0.375rem;
+}
+
+.question-info p {
+  margin: 0.25rem 0;
+}
+
+.question-info-right {
+  border-left-color: var(--page-right);
+}
+
+.question-info-chosen:not(.question-info-right) {
+  border-left-color: var(--page-wrong);
+}
+
+.question-badge {
+  display: inline-block;
+  margin-left: 0.25rem;
+  padding: 0 0.5rem;
+  border-radius: 999px;
+  font-size: 0.875rem;
+  font-weight: 600;
+}
+
+.question-badge-right {
+  background: var(--page-right-background);
+  color: var(--page-right);
+}
+
+.question-badge-chosen {
+  background: var(--page-surface);
+  color: var(--page-text);
+  border: 1px solid var(--page-border);
+}
+
+.question-links li {
+  margin: 0.25rem 0;
+}
+
+.question-more {
+  margin-bottom: 0;
+  font-weight: 600;
+}
+
+.question button {
+  font: inherit;
+  padding: 0.5rem 1rem;
+  border: 2px solid var(--page-accent);
+  border-radius: 0.375rem;
+  background: var(--page-accent);
+  color: var(--page-on-accent);
+  cursor: pointer;
+}
+
+.question button.question-solve {
+  background: var(--page-background);
+  color: var(--page-accent);
+}
+
+.question button:focus-visible,
+.question a:focus-visible,
+.question input:focus-visible,
+.question select:focus-visible,
+.question summary:focus-visible {
+  outline: 3px solid var(--page-text);
+  outline-offset: 2px;
+}
+
+.question-diagnosis {
+  margin: 0.25rem 0 0;
+}