@citolab/tspci 2.12.1 → 2.14.0

package/CHANGELOG.md

@@ -3,6 +3,34 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.14.0](https://github.com/Citolab/tspci/compare/v2.13.0...v2.14.0) (2026-10-14)
+
+
+### Features
+
+* **tspci:** the preact template uses typed store actions and the unsubscribe function ([5297db7](https://github.com/Citolab/tspci/commit/5297db72a3d2c62cdba58c1b2fe49bbbdee1e024))
+
+
+
+
+
+# [2.13.0](/compare/v2.12.1...v2.13.0) (2026-10-14)
+
+
+### Bug Fixes
+
+* **tspci:** give Tailwind 4 variables their defaults in the PCI's shadow root 3d95703
+
+
+### Features
+
+* **tspci:** authoring descriptor, typed settings and a dev page without CDNs 436ef53
+* **tspci:** authoring mode for PCIs that fill settings themselves 5892fa7
+
+
+
+
+
 ## [2.12.1](/compare/v2.12.0...v2.12.1) (2026-08-19)
 
 

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@citolab/tspci",
-  "version": "2.12.1",
+  "version": "2.14.0",
   "description": "an opiniated typescript ims-pci builder with tao integration",
   "author": "patrick <patrick.deklein@cito.nl>",
-  "repository": "@citolab/tspci",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Citolab/tspci.git",
+    "directory": "lib/tspci"
+  },
   "bin": {
     "tspci": "src/cli.js"
   },
@@ -12,11 +16,13 @@
     "init": "tspci init --force --path=../../pcis",
     "test:init:local": "bash ./scripts/test-init-local.sh",
     "test:init:smoke": "bash ./scripts/test-init-local.sh",
-    "test:init:matrix": "bash ./scripts/test-init-matrix.sh"
+    "test:init:matrix": "bash ./scripts/test-init-matrix.sh",
+    "test": "node --test test/*.test.mjs"
   },
   "type": "module",
   "types": "types/index.d.ts",
   "dependencies": {
+    "@citolab/qti-components": "^9.5.0",
     "@compodoc/live-server": "^1.2.3",
     "@inquirer/prompts": "^8.2.0",
     "@rollup/plugin-alias": "^6.0.0",
@@ -30,16 +36,20 @@
     "@tailwindcss/nesting": "0.0.0-insiders.565cd3e",
     "@tailwindcss/postcss": "^4.1.18",
     "autoprefixer": "10.4.23",
+    "bootstrap": "5.1.3",
     "chalk": "5.6.2",
     "chokidar": "^5.0.0",
     "clear": "0.1.0",
     "deepmerge": "^4.3.1",
     "fast-glob": "^3.3.3",
     "figlet": "1.10.0",
+    "htm": "3.1.1",
     "is-module": "^1.0.0",
     "postcss": "^8.5.6",
     "postcss-import": "^16.1.1",
     "postcss-load-config": "^6.0.1",
+    "preact": "10.28.2",
+    "requirejs": "2.3.8",
     "rollup": "^4.59.0",
     "rollup-plugin-livereload": "^2.0.5",
     "tailwindcss": "^4.1.18",
@@ -55,5 +65,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "gitHead": "525a89e24eb69a03fbf3f0b76c33f865f38f44ad"
+  "gitHead": "d72febca7cea937f77be4cef910a7f2d72fd524f"
 }

package/preset/base/AUTHORING.md

@@ -0,0 +1,171 @@
+# Authoring: how an authoring system configures and scores this PCI
+
+A PCI does not only run in a test player. An item author places it in an item in an authoring system (such as
+qti-construction or TAO), sets it up, and decides what counts as a correct answer. This file explains what the
+authoring system learns from your project and what your PCI has to do for it. tspci does the packaging; you only
+fill in two files.
+
+## 1. Settings: `src/config.json`
+
+Every key is a setting of your PCI. In an item it becomes a `data-` attribute (`width` → `data-width`), and your PCI
+receives it in `config.properties` (always as a string, as attributes are).
+
+A value can be a plain default, as in every tspci project:
+
+```json
+{ "title": "Percentages", "width": "200" }
+```
+
+or an object with a `default` plus hints for the author's form:
+
+```json
+{
+  "width": { "default": "200", "editor": "integer", "min": 50, "label": { "en": "Width (px)", "nl": "Breedte (px)" } },
+  "mode": {
+    "default": "mixed",
+    "editor": "enum",
+    "options": [
+      { "value": "mixed", "label": { "en": "Multiple colours" } },
+      { "value": "single", "label": { "en": "One colour" } }
+    ]
+  },
+  "colors": { "default": "#c91a09, #0055bf", "editor": "colorList" }
+}
+```
+
+| editor | the author gets | value |
+| --- | --- | --- |
+| `text` | a text field | any text |
+| `textarea` | a larger text field | any text |
+| `integer`, `number` | a number field (`min`, `max`) | `"200"` |
+| `boolean` | a switch | `"true"` / `"false"` |
+| `enum` | a dropdown of `options` | one of the option values |
+| `color` | a colour picker | `"#4b9f4a"` |
+| `colorList` | a list of colour pickers | `"#c91a09, #0055bf"` |
+| `hidden` | nothing (set by the system, not the author) | |
+| `pci` | a "Configure…" button that opens your PCI's own editor (section 5) | whatever your editor writes, as a string |
+
+A plain value gets an editor from its value: `"true"`/`"false"` a switch, a whole number a number field, the rest a
+text field. `label` is one string or one per language. An authoring system that does not know an editor shows a
+text field, so a hint never makes a setting unusable.
+
+The build passes **only the defaults** to your PCI, so `import configProps from "./config.json"` keeps working. Type
+it with `PciProperties`:
+
+```ts
+import { PciProperties } from "@citolab/tspci";
+import configProps from "./config.json";
+type PropTypes = PciProperties<typeof configProps>; // { width: string; mode: string; ... }
+```
+
+## 2. The response: `package.json` → `config.tspci`
+
+```json
+"config": {
+  "tspci": {
+    "typeIdentifier": "myPci",
+    "label": "My PCI",
+    "response": { "cardinality": "single", "baseType": "integer" },
+    "score": ["MATCH_CORRECT", "NONE"]
+  }
+}
+```
+
+- **`response`** is the response variable your PCI fills with `getResponse()`. It must be what your code returns:
+  `{ base: { integer: 30 } }` is `single` / `integer`. The package's item declares it, and an authoring system uses it
+  for every new item with your PCI.
+- **`score`** lists the scoring your PCI is made for: `MATCH_CORRECT` (the response equals the correct one) and/or
+  `NONE` (not scored, or scored by a person). TAO offers exactly these.
+
+A PCI that reports several values (a moment and a position, say) uses one variable with **record** cardinality:
+QTI binds a PCI to exactly one response variable, and a record has named fields of their own type.
+
+```json
+"response": {
+  "cardinality": "record",
+  "fields": {
+    "time":  { "baseType": "float", "tolerance": "range", "label": { "en": "Moment" } },
+    "point": { "baseType": "point", "tolerance": "area",  "label": { "en": "Position" } }
+  }
+}
+```
+
+`getResponse()` then returns `{ record: [{ name: "time", base: { float: 4.1 } }, { name: "point", base: { point: [455, 250] } }] }`.
+`tolerance` tells the authoring system what kind of margin a score rule may give a field: `range` (between two
+numbers) or `area` (a point inside a shape). Elements the author puts in your `qti-interaction-markup`, such as a
+video, go in `markup`: `"markup": { "video": { "editor": "media", "accept": ["video/*"], "required": true } }`.
+
+## 3. What the build makes of it
+
+`tspci` (and `tspci --dev`) writes `dist/authoring.json`, generated from both files, and warns about what an
+authoring system could not use (an unknown editor, an enum default that is not one of its options, a record field
+without a base type). `tspci --target qti3` puts it in the package next to the bundle, as a file of the PCI resource
+(`resources/pci/authoring.json`), like the SBOM; `--no-authoring` leaves it out. `tspci --target tao` builds TAO's
+settings form from the same `config.json`.
+
+## 4. Correct answers: what your PCI must do
+
+Authors set the correct answer **by answering your PCI** in a preview ("answer in preview"): whatever `getResponse()`
+reports becomes the correct response, or one of several accepted answers. Scoring then compares responses, so:
+
+- **One answer, one response.** Report the meaning, not the route: two ways to build the same thing must give the
+  same response (sort lists, round numbers, leave out ids, order and timestamps). A response that differs in a
+  detail the author did not mean scores 0.
+- **Report the type you declared.** A number as `integer`/`float`, not a JSON string with quotes in it.
+- **Nothing answered, nothing reported.** Return `undefined` until the candidate did something.
+- **Show a given answer.** `setResponse()` and `boundTo` must restore a response, and with `status: "solution"` your
+  PCI receives `responseDeclaration.correctResponse` and should show it (`showCorrectResponse()`); that is how an
+  author checks the answer and how a candidate sees it in review.
+- **Margins live in the item, not in the PCI.** A time window or an area is response processing
+  (`qti-field-value`, `qti-gte`/`qti-lte`, `qti-inside`) that the authoring system writes from the author's rules.
+
+## 5. Authoring mode: settings your PCI edits itself
+
+Some settings cannot be a text field or a number: a shape, a set of areas, a path. Give such a setting
+`"editor": "pci"` and let your PCI edit it. Your PCI then has a second mode, for the item author:
+
+```json
+"partition": { "default": "", "editor": "pci", "label": { "en": "Shape to colour" } }
+```
+
+In `package.json`, `config.tspci.authoring` can set the button text and the size you would like
+(`{ "label": { "en": "Draw the shape…" }, "width": 960, "height": 760 }`). The descriptor then has
+`"authoring": { "properties": ["partition"], ... }`.
+
+Next to `getInstance`, the object you register gets a method that an authoring system calls instead. A player never
+calls it:
+
+```ts
+getAuthoringInstance = (dom: HTMLElement, config: PciAuthoringConfiguration<PropTypes>): PciAuthoringInstance => {
+  // render your editor into dom, starting from config.properties; call config.onchange?.() after each change
+  const instance = {
+    getConfig: () => ({ partition: JSON.stringify(shape) }), // only the "pci" properties, as strings
+    validate: () => (shape.parts < 2 ? ["Draw at least one line"] : []), // optional: what keeps Done from finishing
+    destroy: () => { /* unmount */ },
+  };
+  config.onready?.(instance);
+  return instance;
+};
+```
+
+The authoring system runs this in a sandboxed iframe (TAO calls it directly in its creator page) and owns the
+Done and Cancel buttons. Done writes what
+`getConfig()` returns as `data-` attributes, and delivery reads them like any other setting. Two rules:
+
+- **Delivery must not need authoring mode.** Without the attribute, or with one it cannot read, your PCI uses its
+  default. Other players and authoring systems never call `getAuthoringInstance`, and an authoring system that does
+  not know `pci` shows the setting as a text field.
+- **No messages, no globals.** Your PCI never calls `postMessage`; the authoring system's own page in the iframe does
+  that.
+
+`tspci --dev` shows the button in the config panel: it runs your editor in place of the preview, and Done updates
+the property. See `docs/authoring-mode.md` in the tspci repository for the protocol and the reasons behind it.
+
+## Checklist
+
+- [ ] every setting in `src/config.json` has a `default`, an `editor` and a `label`
+- [ ] `config.tspci.response` matches what `getResponse()` returns
+- [ ] `getResponse()` gives the same response for the same answer, and `undefined` without one
+- [ ] `setResponse()` / `boundTo` and `status: "solution"` show a given response
+- [ ] `npm run prod` writes `dist/authoring.json` without warnings
+- [ ] with an authoring mode: delivery works without the `pci` properties (it uses the defaults)

package/preset/base/global.d.ts

@@ -1,13 +1,23 @@
+// Imports the build bundles into the PCI (see the readme): CSS as a string, images as a data URL.
 declare module "*.css" {
   const content: string;
   export = content;
 }
-
 declare module "*.png" {
   const content: string;
   export = content;
 }
+declare module "*.jpg" {
+  const content: string;
+  export = content;
+}
+declare module "*.svg" {
+  const content: string;
+  export = content;
+}
+
+// Provided by the delivery engine at runtime.
 declare module "qtiCustomInteractionContext" {
   const register: {register: (PortableInteraction) => void};
   export = register;
-}
+}

package/preset/base/package.json

@@ -17,7 +17,16 @@
   },
   "config": {
     "tspci": {
-      "typeIdentifier": "myPci"
+      "typeIdentifier": "myPci",
+      "label": "My PCI",
+      "response": {
+        "cardinality": "single",
+        "baseType": "integer"
+      },
+      "score": [
+        "MATCH_CORRECT",
+        "NONE"
+      ]
     }
   },
   "source": "src/index.ts"

package/preset/base/src/config.json

@@ -1,6 +1,38 @@
 {
-  "title" : "Percentages",
-  "prompt" : "What percentage is colored green?",
-  "width": "200",
-  "height": "200"
-}
+  "title": {
+    "default": "Percentages",
+    "editor": "text",
+    "label": { "en": "Title", "nl": "Titel" }
+  },
+  "question": {
+    "default": "What percentage of the circle is coloured?",
+    "editor": "textarea",
+    "label": { "en": "Question", "nl": "Vraag" }
+  },
+  "segments": {
+    "default": "10",
+    "editor": "integer",
+    "min": 2,
+    "max": 24,
+    "label": { "en": "Number of slices", "nl": "Aantal stukken" }
+  },
+  "colored": {
+    "default": "3",
+    "editor": "integer",
+    "min": 0,
+    "max": 24,
+    "label": { "en": "Coloured slices", "nl": "Gekleurde stukken" }
+  },
+  "color": {
+    "default": "#3b82f6",
+    "editor": "color",
+    "label": { "en": "Colour", "nl": "Kleur" }
+  },
+  "size": {
+    "default": "200",
+    "editor": "integer",
+    "min": 100,
+    "max": 400,
+    "label": { "en": "Size of the circle (px)", "nl": "Grootte van de cirkel (px)" }
+  }
+}

package/preset/base/src/styles.css

@@ -1,3 +1,96 @@
-h1 {
-    color: red;
-}
+/* Rendered inside the PCI's shadow root: these rules do not leak into the item, and the item's CSS does not leak in. */
+
+:host {
+  display: block;
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  color: #1f2933;
+}
+
+.pci {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+  width: fit-content;
+  max-width: 100%;
+  margin: 0 auto;
+  padding: 24px 28px;
+  border: 1px solid #e3e8ee;
+  border-radius: 16px;
+  background: linear-gradient(180deg, #ffffff 0%, #f7f9fb 100%);
+  box-shadow: 0 1px 2px rgba(16, 24, 40, 0.04), 0 8px 24px rgba(16, 24, 40, 0.06);
+}
+
+.title {
+  margin: 0;
+  font-size: 1.25rem;
+  font-weight: 650;
+  letter-spacing: -0.01em;
+}
+
+/* Scales down on a narrow screen; the viewBox keeps the drawing sharp. */
+.pie {
+  max-width: 100%;
+  height: auto;
+  filter: drop-shadow(0 2px 3px rgba(16, 24, 40, 0.15));
+}
+
+.slice {
+  stroke: #ffffff;
+  stroke-width: 2;
+}
+/* Coloured slices carry a fill attribute (the author's colour); the others are grey. */
+.slice:not([fill]) {
+  fill: #e5e9f0;
+}
+
+.question {
+  max-width: 32ch;
+  text-align: center;
+  color: #52606d;
+  cursor: pointer;
+}
+
+.answer {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 1.125rem;
+  font-weight: 600;
+}
+
+input {
+  width: 4.5ch;
+  padding: 8px 10px;
+  font: inherit;
+  text-align: right;
+  color: inherit;
+  border: 1.5px solid #cbd2d9;
+  border-radius: 10px;
+  background: #ffffff;
+  transition: border-color 120ms, box-shadow 120ms;
+  -moz-appearance: textfield;
+  appearance: textfield;
+}
+/* A percentage is typed, not stepped: hide the spin buttons. */
+input::-webkit-outer-spin-button,
+input::-webkit-inner-spin-button {
+  -webkit-appearance: none;
+  margin: 0;
+}
+/* Keep a clearly visible focus ring for keyboard users. */
+input:focus-visible {
+  outline: none;
+  border-color: #3b82f6;
+  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.3);
+}
+input[aria-invalid="true"] {
+  border-color: #e11d48;
+  box-shadow: 0 0 0 3px rgba(225, 29, 72, 0.2);
+}
+input:disabled {
+  background: #f1f5f9;
+  color: #52606d;
+  cursor: not-allowed;
+}