Dev (#1)

Reviewed-on: #1

src/export/typst/templates/exam.typ

@@ -0,0 +1,222 @@
+// coursebank — exam paper template
+//
+// This file is a template, not generated output. `coursebank export typst`
+// replaces only the marked regions below and leaves every other line exactly as
+// you wrote it, so this is where layout decisions belong.
+//
+//   coursebank template dump          write this file into templates/
+//   typst watch templates/exam.typ    restyle it against the sample data
+//
+// The regions ship with sample values so that last command works before any
+// export has happened. Two markers are in play:
+//
+//   // coursebank:begin meta        a dictionary of course and form metadata
+//   // coursebank:end meta
+//   // coursebank:begin questions   one #render-question(...) call per item
+//   // coursebank:end questions
+//
+// An exported document keeps its markers, so exporting into a file you have since
+// restyled replaces the questions and leaves the styling alone.
+//
+// Note what is *not* in the payload for this variant: there is no `correct` field
+// on an option, because the render config for the paper withholds it. That is
+// deliberate. Do not switch `reveal` to `key` here in order to build a solutions
+// copy — export the `key` variant instead, or the day you forget an `if` is the
+// day the class gets the answers.
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Metadata
+// ─────────────────────────────────────────────────────────────────────────────
+
+// coursebank:begin meta
+#let cb-meta = (
+  course: (code: "COURSE 101", title: "Sample Course", term: "2026s"),
+  assessment: (
+    id: "sample",
+    title: "Sample assessment",
+    date: "2026-01-01",
+    minutes-allowed: 50.0,
+    instructions: [Choose the single best answer unless a question says otherwise.],
+  ),
+  form: (id: "A", count: 1),
+  totals: (questions: 1, scored: 1, bonus: 0, points: 1.5, bonus-points: 0.0),
+  extra: (:),
+)
+// coursebank:end meta
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Settings
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Anything under `extra` in templates/typst.yaml arrives here untouched, which is
+// how a course changes the look without editing this file at all.
+#let extra = cb-meta.at("extra", default: (:))
+#let accent = rgb(extra.at("accent", default: "#1f4e79"))
+#let body-font = extra.at("font", default: "Libertinus Serif")
+#let body-size = eval(extra.at("font-size", default: "11pt"))
+#let paper = extra.at("paper", default: "us-letter")
+#let show-name-block = extra.at("name-block", default: true)
+#let show-points = extra.at("show-points", default: true)
+#let page-per-item = extra.at("page-per-item", default: false)
+
+#let form-note = if cb-meta.form.at("count", default: 1) > 1 {
+  " · Form " + cb-meta.form.id
+} else {
+  ""
+}
+
+#set page(
+  paper: paper,
+  margin: 2cm,
+  header: text(size: 0.85em)[
+    #cb-meta.course.code · #cb-meta.assessment.title#form-note
+  ],
+  footer: context text(size: 0.85em)[
+    #counter(page).display("Page 1 of 1", both: true)
+  ],
+)
+#set text(font: body-font, size: body-size, lang: "en")
+#set par(justify: false, leading: 0.65em)
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Markup arrives as content when the render config says `content: content`, and as
+// a string when it says `content: str`. Accepting both means switching that
+// setting does not require editing the template.
+#let markup(v) = if type(v) == str { eval(v, mode: "markup") } else { v }
+
+// 1 point, 2 points, 1.5 points.
+#let fmt-points(p) = {
+  let n = if p == calc.trunc(p) { str(calc.trunc(p)) } else { str(p) }
+  n + if p == 1 { " point" } else { " points" }
+}
+
+#let points-tag(q) = {
+  let p = q.at("points", default: none)
+  let bonus = q.at("bonus", default: false)
+  let label = if bonus and show-points and p != none {
+    "bonus, " + fmt-points(p)
+  } else if bonus {
+    "bonus"
+  } else if show-points and p != none {
+    fmt-points(p)
+  } else {
+    none
+  }
+  if label != none {
+    text(fill: luma(100), size: 0.9em)[(#label)]
+  }
+}
+
+#let stimulus-block(s) = {
+  block(stroke: 0.5pt + luma(180), inset: 8pt, radius: 3pt, width: 100%)[
+    #markup(s.body)
+  ]
+  let caption = s.at("caption", default: none)
+  if caption != none {
+    block(above: 0.3em)[#text(size: 0.85em, style: "italic")[#markup(caption)]]
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The renderer
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// One question, one function. Rename it if you like and set `question-fn` in
+// templates/typst.yaml to match. It takes a single dictionary so that turning a
+// field on or off in the config never changes this signature.
+
+#let render-question(q) = {
+  // A stimulus shared by several items is printed with each of them. That repeats
+  // material, but a student should never have to turn a page to find the passage a
+  // question refers to.
+  let s = q.at("stimulus", default: none)
+  if s != none { stimulus-block(s) }
+
+  // The number is the one recorded in the assessment record, not the position on
+  // the page. Keep it that way: it is the join key to every grading export.
+  //
+  // Built in code rather than written as `*#q.number.*` because a field access
+  // followed by a literal period reads as the start of another field access.
+  let number-label = str(q.number) + "."
+
+  block(above: 1.2em, below: 0.5em)[
+    *#number-label* #points-tag(q) #markup(q.stem)
+  ]
+
+  if q.at("multi-select", default: false) {
+    block(below: 0.4em)[
+      #text(size: 0.9em, style: "italic")[Select all that apply.]
+    ]
+  }
+
+  block(inset: (left: 1.2em))[
+    #for opt in q.at("options", default: ()) {
+      grid(
+        columns: (1.4em, 1fr),
+        gutter: 0.2em,
+        [#(opt.letter + ".")], [#markup(opt.text)],
+      )
+      v(0.15em)
+    }
+  ]
+
+  if page-per-item { pagebreak(weak: true) }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The page
+// ─────────────────────────────────────────────────────────────────────────────
+
+#align(center)[
+  #text(size: 1.4em, weight: "bold", fill: accent)[#cb-meta.assessment.title]\
+  #text(size: 0.95em)[
+    #cb-meta.course.code — #cb-meta.course.title · #cb-meta.assessment.term
+  ]\
+  #text(size: 0.9em)[
+    #cb-meta.assessment.at("date", default: "")
+    #{
+      let m = cb-meta.assessment.at("minutes-allowed", default: none)
+      if m != none { " · " + str(int(calc.round(m))) + " minutes" }
+    }
+    #{
+      let p = cb-meta.totals.at("points", default: none)
+      if p != none { " · " + fmt-points(p) }
+    }
+  ]
+]
+
+#if show-name-block {
+  block(above: 1em, below: 1.5em)[
+    #grid(
+      columns: (auto, 1fr, auto, 1fr),
+      gutter: 0.6em,
+      [*Name*], box(width: 100%, repeat[.]), [*Student ID*], box(width: 100%, repeat[.]),
+    )
+  ]
+}
+
+#{
+  let instructions = cb-meta.assessment.at("instructions", default: none)
+  if instructions != none {
+    block(fill: luma(245), inset: 8pt, radius: 3pt, width: 100%)[
+      #markup(instructions)
+    ]
+  }
+}
+
+// coursebank:begin questions
+#render-question((
+  number: 1,
+  points: 1.5,
+  bonus: false,
+  multi-select: false,
+  stem: [This sample question is replaced on the next export.],
+  options: (
+    (letter: "A", position: 1, text: [The first option.]),
+    (letter: "B", position: 2, text: [The second option.]),
+  ),
+))
+// coursebank:end questions