@citolab/tspci 2.12.0 → 2.13.0

package/src/authoring.js

@@ -0,0 +1,114 @@
+// The authoring descriptor: what an authoring system needs to know to configure and score a PCI.
+//
+// A PCI developer writes two files tspci projects already have:
+//   src/config.json        the data- properties: a default value, or { default, editor, label, ... }
+//   package.json           config.tspci: typeIdentifier, label, markup slots and the response shape
+// The build turns them into
+//   the bundle             only the defaults (flattenConfig), as before
+//   dist/authoring.json    the descriptor (buildDescriptor), shipped next to the bundle like the SBOM
+// See AUTHORING.md (in every project tspci init creates) and the readme, "Authoring systems".
+
+export const DESCRIPTOR_VERSION = "0";
+export const DESCRIPTOR_FILE = "authoring.json";
+
+/**
+ * Editors for a data- property. An authoring system that does not know one shows a text field.
+ * `pci`: the PCI fills it itself, in its authoring mode (`getAuthoringInstance`, see AUTHORING.md "Authoring mode").
+ */
+export const PROPERTY_EDITORS = ["text", "textarea", "integer", "number", "boolean", "enum", "color", "colorList", "hidden", "pci"];
+
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** config.json → the plain defaults the PCI receives (every value a string, as a data- attribute gives it). */
+export function flattenConfig(config) {
+  const flat = {};
+  for (const [key, entry] of Object.entries(config ?? {})) {
+    flat[key] = isObject(entry) ? String(entry.default ?? "") : String(entry);
+  }
+  return flat;
+}
+
+/** A plain config.json value, as tspci PCIs always had: the editor follows from the value (as tspci-tao does). */
+const editorFor = (value) => (/^(true|false)$/.test(value) ? "boolean" : /^-?\d+$/.test(value) ? "integer" : "text");
+
+function toProperty(key, entry, problems) {
+  if (!isObject(entry)) {
+    const value = String(entry);
+    return { editor: editorFor(value), default: value };
+  }
+  const { default: value = "", editor = "text", $comment, ...rest } = entry;
+  if (!PROPERTY_EDITORS.includes(editor)) {
+    problems.push(`config.json ${key}: unknown editor "${editor}" (one of ${PROPERTY_EDITORS.join(", ")})`);
+  }
+  if (editor === "enum") {
+    const options = Array.isArray(rest.options) ? rest.options : [];
+    if (!options.length) problems.push(`config.json ${key}: an enum needs options`);
+    rest.options = options.map((o) => (isObject(o) ? o : { value: String(o) }));
+    if (value !== "" && !rest.options.some((o) => String(o.value) === String(value))) {
+      problems.push(`config.json ${key}: the default "${value}" is not one of the options`);
+    }
+  }
+  return { editor, default: String(value), ...rest };
+}
+
+function checkResponse(response, problems) {
+  if (!response) return;
+  const cardinality = response.cardinality ?? "single";
+  if (!["single", "multiple", "ordered", "record"].includes(cardinality)) {
+    problems.push(`config.tspci.response.cardinality: "${cardinality}" is not a QTI cardinality`);
+  }
+  if (cardinality === "record") {
+    const fields = Object.entries(response.fields ?? {});
+    if (!fields.length) problems.push("config.tspci.response: a record needs fields");
+    for (const [name, field] of fields) {
+      if (!field?.baseType) problems.push(`config.tspci.response.fields.${name}: baseType is missing`);
+    }
+  } else if (!response.baseType) {
+    problems.push("config.tspci.response: baseType is missing");
+  }
+}
+
+/**
+ * The authoring mode of a PCI: present when a property has editor `pci`. config.tspci.authoring adds a label for the
+ * button that opens it and the size the PCI would like for it.
+ */
+function toAuthoring(authoring, properties, problems) {
+  const managed = Object.keys(properties).filter((key) => properties[key].editor === "pci");
+  if (!managed.length) {
+    if (authoring) problems.push("config.tspci.authoring: no property in config.json has editor \"pci\", so there is nothing to author");
+    return null;
+  }
+  return { properties: managed, ...(isObject(authoring) ? authoring : {}) };
+}
+
+/**
+ * The descriptor of a PCI project. `problems` lists what an authoring system could not use (an unknown editor, an
+ * enum default that is not an option, a record field without a base type); the build reports them as warnings.
+ */
+export function buildDescriptor(packageJson, config) {
+  const tspci = packageJson?.config?.tspci ?? {};
+  const problems = [];
+  if (!tspci.typeIdentifier) problems.push("package.json config.tspci.typeIdentifier is missing");
+
+  const properties = {};
+  for (const [key, entry] of Object.entries(config ?? {})) properties[key] = toProperty(key, entry, problems);
+
+  const response = tspci.response ?? { cardinality: "single", baseType: "string" };
+  checkResponse(response, problems);
+  const authoring = toAuthoring(tspci.authoring, properties, problems);
+
+  return {
+    descriptor: {
+      descriptorVersion: DESCRIPTOR_VERSION,
+      typeIdentifier: tspci.typeIdentifier ?? "",
+      version: packageJson?.version ?? "",
+      label: tspci.label ?? packageJson?.name ?? "",
+      properties,
+      markup: tspci.markup ?? {},
+      response,
+      ...(tspci.score ? { score: tspci.score } : {}),
+      ...(authoring ? { authoring } : {}),
+    },
+    problems,
+  };
+}

package/src/rollup-plugin-authoring.js

@@ -0,0 +1,32 @@
+import fs from "fs";
+import path from "path";
+import { buildDescriptor, DESCRIPTOR_FILE, flattenConfig } from "./authoring.js";
+
+/**
+ * - `import config from "./config.json"` gets the plain defaults, also when config.json carries editor hints
+ *   (`{ "default": "640", "editor": "integer", ... }`), so the hints never end up in the bundle;
+ * - writes dist/authoring.json, the descriptor an authoring system reads (see authoring.js).
+ * Runs before @rollup/plugin-json, which then turns the flattened JSON into a module.
+ */
+export function authoring({ projectRoot = process.cwd(), configFile = "src/config.json" } = {}) {
+  const configPath = path.resolve(projectRoot, configFile);
+  return {
+    name: "tspci-authoring",
+
+    transform(code, id) {
+      if (path.resolve(id.split("?")[0]) !== configPath) return null;
+      return { code: JSON.stringify(flattenConfig(JSON.parse(code)), null, 2), map: null };
+    },
+
+    writeBundle(options) {
+      const packageJson = JSON.parse(fs.readFileSync(path.join(projectRoot, "package.json"), "utf8"));
+      const config = fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, "utf8")) : {};
+      const { descriptor, problems } = buildDescriptor(packageJson, config);
+      for (const problem of problems) this.warn(problem);
+
+      const outputDir = options.dir ?? path.dirname(options.file ?? path.join(projectRoot, "dist", "index.js"));
+      fs.mkdirSync(outputDir, { recursive: true });
+      fs.writeFileSync(path.join(outputDir, DESCRIPTOR_FILE), `${JSON.stringify(descriptor, null, 2)}\n`, "utf8");
+    },
+  };
+}

package/src/rollup-plugin-postcss-string.js

@@ -1,6 +1,41 @@
 import postcss from "postcss";
 import loadPostCssConfig from "postcss-load-config";
 
+/**
+ * A PCI renders in a shadow root, and browsers ignore `@property` there, so Tailwind 4's registered `--tw-*` variables
+ * lose both their initial value and `inherits: false`:
+ * - without the initial value, `border` has no style (`--tw-border-style: solid`), `-translate-x-1/2` no y value and
+ *   `ring`/`shadow` nothing: borders, shadows and rings silently disappear;
+ * - without `inherits: false`, a variable set on a parent leaks into its children (`ring-inset` on a wrapper makes the
+ *   rings inside it inset too).
+ * This sets every `inherits: false` property on every element in the earliest layer (`properties`), which every
+ * utility still overrides: to its initial value, or to `initial` (the guaranteed-invalid value, as if unset) when it has
+ * none. That resets it per element instead of inheriting it. `inherits: true` properties inherit anyway and are left out.
+ * CSS without `@property` is left as it is.
+ */
+export function shadowRootPropertyDefaults(root) {
+  const defaults = [];
+  root.walkAtRules("property", (rule) => {
+    const name = rule.params.trim();
+    let initial;
+    let inherits;
+    rule.walkDecls((decl) => {
+      if (decl.prop === "initial-value") initial = decl.value;
+      if (decl.prop === "inherits") inherits = decl.value.trim();
+    });
+    if (name.startsWith("--") && inherits === "false") {
+      defaults.push(postcss.decl({ prop: name, value: initial ?? "initial" }));
+    }
+  });
+  if (defaults.length === 0) {
+    return root;
+  }
+  const rule = postcss.rule({ selectors: [":host", "*", "::before", "::after", "::backdrop"] });
+  rule.append(defaults);
+  root.append(postcss.atRule({ name: "layer", params: "properties", nodes: [rule] }));
+  return root;
+}
+
 export function postcssString(options = {}) {
   const extensions = options.extensions || [".css"];
   const configEnabled = options.config !== false;
@@ -47,8 +82,9 @@ export function postcssString(options = {}) {
         map: false,
       });
 
+      const css = shadowRootPropertyDefaults(result.root).toString();
       return {
-        code: `export default ${JSON.stringify(result.css)};`,
+        code: `export default ${JSON.stringify(css)};`,
         map: { mappings: "" },
       };
     },

package/src/rollup.config.dev.js

@@ -2,16 +2,33 @@ import livereload from "rollup-plugin-livereload";
 // PK: not the official npm package, but a copy, needed watch functionality
 import { liveServer } from "./rollup-plugin-live-server.js";
 import { copyFiles } from "./rollup-plugin-copy-files.js";
+import fs from "fs";
 import path from "path";
+import { createRequire } from "module";
 import rollupConfig from "./rollup.config.js"; // Make sure this exports an object with `output` and `plugins`
 
 const PACKAGE_ROOT_PATH = process.cwd();
 const PACKAGE_DIST_PATH = path.join(PACKAGE_ROOT_PATH, "dist");
 
+// The dev page (public/index.html) loads its libraries from /vendor/<package>, served from tspci's own dependencies, so
+// it needs no public CDN and runs the versions in the lockfile: RequireJS, Bootstrap, preact + htm, and qti-components
+// (the PCI host, and the RequireJS / bundle / stylesheet it gives the PCI iframe).
+const require = createRequire(import.meta.url);
+// The folder of an installed package, found the way Node looks for it (the node_modules folders up from here), so a
+// package's "exports" (import-only, or without package.json) does not matter.
+const packageDir = (name) => {
+  const dir = (require.resolve.paths(name) ?? [])
+    .map((modules) => path.join(modules, name))
+    .find((candidate) => fs.existsSync(path.join(candidate, "package.json")));
+  if (!dir) throw new Error(`tspci dev page: ${name} is not installed`);
+  return dir;
+};
+const VENDOR_PACKAGES = ["requirejs", "bootstrap", "preact", "htm", "@citolab/qti-components"];
+
 // Configure live server
 const livesrvr = liveServer({
   root: path.join(PACKAGE_ROOT_PATH),
-  mount: [["/", "./dist"]],
+  mount: [["/", "./dist"], ...VENDOR_PACKAGES.map((name) => [`/vendor/${name}`, packageDir(name)])],
   open: true,
   wait: 500,
   watch: PACKAGE_DIST_PATH,

package/src/rollup.config.js

@@ -7,6 +7,7 @@ import commonjs from "@rollup/plugin-commonjs"; // added this when added react-r
 import json from "@rollup/plugin-json";
 import { postcssString } from "./rollup-plugin-postcss-string.js";
 import { copyFiles } from "./rollup-plugin-copy-files.js";
+import { authoring } from "./rollup-plugin-authoring.js";
 
 import fs from "fs";
 import path from "path";
@@ -52,6 +53,7 @@ export default {
       browser: true
     }),
     commonjs({ transformMixedEsModules: true }), // preact was imported twice, with require (unistore/preact) and with import (our import), which resulted in 2 preacts in our project
+    authoring({ projectRoot: PACKAGE_ROOT_PATH }), // config.json → plain defaults in the bundle, dist/authoring.json for authoring systems
     json(), // used to import config.json
     typescript({
       tsconfig: `${PACKAGE_ROOT_PATH}/tsconfig.json`,

package/types/index.d.ts

@@ -32,6 +32,132 @@ export interface ResponseDeclaration {
   correctResponse?: CorrectResponse;
 }
 
+/**
+ * The properties a PCI receives, for a config.json whose values may carry editor hints
+ * (`{ "default": "640", "editor": "integer" }`): the build passes only the defaults, and like every data-
+ * attribute they arrive as strings. Use `type PropTypes = PciProperties<typeof configProps>`.
+ */
+export type PciProperties<T> = { [K in keyof T]: string };
+
+/** A translatable text in the authoring descriptor: one string, or one per language (`{ "en": …, "nl": … }`). */
+export type AuthoringText = string | Record<string, string>;
+
+/**
+ * How an authoring system edits a data- property (config.json). Unknown editors fall back to a text field.
+ * `pci`: the PCI fills it itself in its authoring mode (see IMSpciAuthoringFactory).
+ */
+export type AuthoringPropertyEditor =
+  | "text" | "textarea" | "integer" | "number" | "boolean" | "enum" | "color" | "colorList" | "hidden" | "pci";
+
+export interface AuthoringProperty {
+  editor: AuthoringPropertyEditor;
+  /** The default, as the data- attribute holds it. */
+  default: string;
+  label?: AuthoringText;
+  /** enum: the values to choose from. */
+  options?: { value: string; label?: AuthoringText }[];
+  /** integer / number */
+  min?: number;
+  max?: number;
+  [hint: string]: unknown;
+}
+
+/** A field of a record response (several values in one response variable). */
+export interface AuthoringResponseField {
+  baseType: string;
+  /** How the authoring system edits the correct value (e.g. "mediaTime", "mediaPoint"); a text field by default. */
+  editor?: string;
+  label?: AuthoringText;
+  /** The kind of margin a score rule may give it: "range" (numbers), "area" (points). */
+  tolerance?: string;
+  [hint: string]: unknown;
+}
+
+/**
+ * dist/authoring.json, generated from src/config.json and package.json config.tspci, and shipped next to the bundle.
+ * See AUTHORING.md.
+ */
+export interface AuthoringDescriptor {
+  descriptorVersion: string;
+  typeIdentifier: string;
+  version: string;
+  label: string;
+  properties: Record<string, AuthoringProperty>;
+  /** Elements the item puts in qti-interaction-markup, e.g. `{ "video": { "editor": "media", "accept": ["video/*"] } }`. */
+  markup: Record<string, { editor: string; element?: string; accept?: string[]; required?: boolean; label?: AuthoringText }>;
+  response:
+    | { cardinality: "single" | "multiple" | "ordered"; baseType: string }
+    | { cardinality: "record"; fields: Record<string, AuthoringResponseField> };
+  /** The response processing templates the PCI is meant for (TAO's score setting), e.g. ["MATCH_CORRECT", "NONE"]. */
+  score?: string[];
+  /** Present when the PCI has an authoring mode: properties with editor "pci", plus config.tspci.authoring. */
+  authoring?: AuthoringMode;
+}
+
+/** The authoring mode in the descriptor. The authoring system shows one button that opens it. */
+export interface AuthoringMode {
+  /** The properties the PCI fills itself (editor "pci"), in config.json order. */
+  properties: string[];
+  /** The text of the button, e.g. `{ "en": "Draw the shape…", "nl": "Vorm tekenen…" }`. */
+  label?: AuthoringText;
+  /** The size (px) the authoring UI would like; the authoring system may give less. */
+  width?: number;
+  height?: number;
+  [hint: string]: unknown;
+}
+
+/**
+ * What the authoring system passes to getAuthoringInstance. `properties` are the item's data- properties, all of
+ * them (also the ones the PCI does not fill itself, so it can show the shape in the item's colours), as strings.
+ */
+export interface PciAuthoringConfiguration<T> {
+  properties: Partial<T>;
+  /** The UI language of the authoring system ("nl", "en"). */
+  language?: string;
+  /** Call when the authoring UI is ready to be used. */
+  onready?: (instance: PciAuthoringInstance) => void;
+  /** Call after every change the author makes (the host may enable "Done" or warn about unsaved work). */
+  onchange?: () => void;
+}
+
+/** A PCI in authoring mode: the author shapes its configuration, the host asks for it when the author is done. */
+export interface PciAuthoringInstance {
+  /** The managed properties (descriptor authoring.properties) as data- attribute strings; others are ignored. */
+  getConfig: () => Record<string, string>;
+  /** What keeps the configuration from being used (shown to the author, "Done" waits for an empty list). */
+  validate?: () => string[];
+  destroy?: () => void;
+}
+
+
+/**
+ * postMessage protocol between an authoring system (host) and the sandboxed iframe it runs a PCI's authoring mode in.
+ * The frame is the host's own bootstrap page; the PCI itself never posts messages.
+ *
+ * Every message carries `version`: the protocol version of its sender, 1 for this protocol. It goes up only for a change
+ * the other side cannot handle (a new optional field keeps it). The frame checks it on init, the host on hello; a
+ * mismatch is reported as an error.
+ */
+export type PciAuthoringProtocolVersion = 1;
+
+type Versioned<M> = M & { version: PciAuthoringProtocolVersion };
+
+export type PciAuthoringHostMessage = Versioned<
+  /** After the frame said hello: what to load and with which properties. */
+  | { type: "pci-authoring:init"; moduleUrl: string; typeIdentifier: string; properties: Record<string, string>; language?: string }
+  /** The author pressed "Done": reply with pci-authoring:config. */
+  | { type: "pci-authoring:request-config" }
+>;
+
+export type PciAuthoringFrameMessage = Versioned<
+  | { type: "pci-authoring:hello" }
+  | { type: "pci-authoring:ready" }
+  | { type: "pci-authoring:change" }
+  | { type: "pci-authoring:config"; config: Record<string, string>; problems: string[] }
+  /** The module did not load, has no getAuthoringInstance, or the host speaks another protocol version. */
+  | { type: "pci-authoring:error"; message: string }
+>;
+
 // Define the ConfigProperties interface
 export interface ConfigProperties<T> {
   properties: T; // Follows dataset conversion rules (camelCased keys)
@@ -81,6 +207,16 @@ export interface IMSpciFactory<T> {
   getInstance: (dom: HTMLElement, configuration: ConfigProperties<T>, state?: string) => IMSpci<T>;
 }
 
+/**
+ * The QTI 3 PCI (the object registered with qtiCustomInteractionContext) extended with an authoring mode:
+ * getAuthoringInstance next to getInstance. Delivery engines only know getInstance and never call it, so the PCI works
+ * in every QTI 3 player as before; an authoring system that supports it checks
+ * `typeof pci.getAuthoringInstance === "function"` and calls it instead of getInstance. See AUTHORING.md, "Authoring mode".
+ */
+export interface IMSpciAuthoringFactory<T> extends IMSpciFactory<T> {
+  getAuthoringInstance: (dom: HTMLElement, configuration: PciAuthoringConfiguration<T>) => PciAuthoringInstance;
+}
+
 export interface directedPair {
   destination: string;
   source: string;