@citolab/tspci-tao 2.12.1 → 2.13.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.13.0](https://github.com/Citolab/tspci/compare/v2.12.1...v2.13.0) (2026-10-14)
+
+
+### Features
+
+* **tspci-tao:** typed properties form and a Configure button in TAO ([406a940](https://github.com/Citolab/tspci/commit/406a940fde13990c14bda3984a8a4451c49617d1))
+
+
+
+
+
 ## [2.12.1](https://github.com/Citolab/tspci/compare/v2.12.0...v2.12.1) (2026-08-19)
 
 **Note:** Version bump only for package @citolab/tspci-tao

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@citolab/tspci-tao",
-  "version": "2.12.1",
+  "version": "2.13.0",
   "description": "create a zip file that can be imported into TAO",
   "author": "patrick <patrick.deklein@cito.nl>, Marcel Hoekstra <marcel.hoekstra@cito.nl>",
-  "repository": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Citolab/tspci.git",
+    "directory": "lib/tspci-tao"
+  },
   "type": "module",
   "types": "types/index.d.ts",
   "dependencies": {
@@ -16,5 +20,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "gitHead": "525a89e24eb69a03fbf3f0b76c33f865f38f44ad"
+  "gitHead": "b62ff736df6ebd0ec8c86e35338a6bb705e0820c"
 }

package/readme.md

@@ -13,6 +13,53 @@ This package allows the @citolab/tspci-bundler to create a package which can be
 
 PCI's can be imported in TAO as a ZIP file. The ZIP generated contains the PCI itself and metadata enabling the PCI to be shown in the TAO creator platform.
 Configuration of a PCI can be done by the author because this packager reads the config.json file in the src folder
+A `config.json` value may also be an object with a `default` and editor hints (the authoring descriptor, see
+[@citolab/tspci](https://github.com/Citolab/tspci/tree/main/lib/tspci#authoring-systems)). TAO's properties form then
+shows the setting's `label` (the English one when it is given per language), with its `hint` (else the label) in the
+tooltip, and a control for its `editor`:
+
+| editor | TAO's form shows | the PCI gets |
+| --- | --- | --- |
+| `text` | a text field | the text |
+| `textarea` | a larger text field | the text |
+| `integer`, `number` | a number field with `min`, `max` and `step` (1 for an integer) | `"200"` |
+| `boolean` | a checkbox | `"true"` / `"false"` |
+| `enum` | a dropdown with the labels of the `options` | the option's value |
+| `color` | a colour picker and a hex field, kept in sync | `"#4b9f4a"` |
+| `colorList` | a colour picker per colour, with a button to add one and one to remove each (at least one stays) | `"#c91a09, #0055bf"` |
+| `hidden` | nothing; the interaction keeps the default | the default |
+| `pci` | a text field below the "Configure…" button (see below) | what the PCI's editor writes |
+| another | a text field | the text |
+
+A setting given as a plain default (`"width": "200"`) keeps the field it always had: its name as the label, and a
+number field for a whole number, else a text field. Every change is written to the interaction and passed to the
+PCI's `trigger`, as text, the way a `data-` attribute gives it.
+
+The editor hints are read by `buildDescriptor` of the project's `@citolab/tspci` (as for `dist/authoring.json`). With
+an older `@citolab/tspci` without it, every setting gets a text field.
+
+### Authoring mode: "Configure…"
+
+Settings with `editor: "pci"` are filled by the PCI itself, in its authoring mode (`getAuthoringInstance`, see
+[@citolab/tspci](https://github.com/Citolab/tspci/tree/main/lib/tspci) AUTHORING.md, "Authoring mode"). For such a PCI
+the properties form gets a button above the first of those settings. Its text is `config.tspci.authoring.label` in
+package.json (the English one when it is given per language, through TAO's translations), or "Configure…".
+
+The button opens TAO's modal with the PCI's authoring UI in it, sized after `config.tspci.authoring.width/height` (at
+most 70% of the window height). The PCI gets all current settings of the interaction and TAO's UI language.
+
+- **Done** asks the PCI to `validate()`. Problems are shown, and the dialog stays open. Otherwise the settings that
+  `getConfig()` returns (only the `pci` ones) are written to the interaction and passed to the PCI's `trigger`,
+  like a change in the form, and the dialog closes.
+- **Cancel**, the close button or Escape close it without changes.
+
+The text field of a `pci` setting stays below the button: it is the way to clear the value (back to the PCI's
+default), to copy it from another item, and the only way to change it when the module has no authoring mode. In
+that case the dialog says so instead of showing the editor.
+
+TAO runs the creator in its own page with RequireJS, so the button calls the runtime module directly; there is no
+iframe and no message protocol, unlike authoring systems that sandbox the PCI. A PCI without `pci` settings gets
+exactly the package it got before.
 
 If scoring can be done with a MATCH_CORRECT (single string comparison) the item author can provide the correct answer in TAO by interaction with the PCI.
 This way one PCI can be re-used in different configurations supporting multiple items.

package/src/createPackage.mjs

@@ -1,8 +1,10 @@
 import fs, { mkdirSync } from "fs";
 import path from "path";
+import { createRequire } from "module";
+import { fileURLToPath, pathToFileURL } from "url";
 import yazl from "yazl";
 
-export const bundle = () => {
+export const bundle = async () => {
   const PACKAGE_ROOT_PATH = process.cwd();
 
   const PACKAGER_PATH = path.join(
@@ -107,27 +109,43 @@ export const bundle = () => {
   // ---------------------------------------------------------------------
 
   // add variables from taoConfigValues, to be able to configurate PCI's
+  let authoringOptions = null;
+  let controlsOptions = null;
   const configPath = path.join(PACKAGE_ROOT_PATH, "src/config.json");
 
   if (fs.existsSync(configPath)) {
     let configValues;
     let configJson = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    // the editor hints, read the way the tspci build reads them for dist/authoring.json
+    const properties = await describedProperties(PACKAGE_ROOT_PATH, packageData, configJson);
     configValues = Object.keys(configJson).reduce((acc, elem) => {
-      const defaultValue = configJson[elem];
+      // A config.json value is a default, or { default, editor, label, ... } (the authoring descriptor, see
+      // AUTHORING.md): TAO's form gets the default, and the editor decides the field when there is one.
+      const entry = configJson[elem];
+      const described = entry !== null && typeof entry === "object" && !Array.isArray(entry);
+      const defaultValue = described ? String(entry.default ?? "") : entry;
 
       let type = "string";
-      if (Number.isInteger(parseInt(defaultValue))) {
+      if (described && (entry.editor === "integer" || entry.editor === "number")) {
+        type = "number";
+      } else if (described && entry.editor === "boolean") {
+        type = "boolean";
+      } else if (!described && /^-?\d+$/.test(String(defaultValue))) {
         type = "number";
       }
-      if (isBoolean(defaultValue)) {
+      if (!described && isBoolean(defaultValue)) {
         type = "boolean";
       }
 
       acc.push({
         name: `${elem}`,
         type,
-        defaultValue: `"${defaultValue}"`, // type === "number" ? `${defaultValue}` : `"${defaultValue}"`,
+        // a described default goes into the creator's code as a JS string literal, so quotes and newlines are safe
+        defaultValue: described ? JSON.stringify(defaultValue) : `"${defaultValue}"`, // type === "number" ? `${defaultValue}` : `"${defaultValue}"`,
         optional: true,
+        managed: described && entry.editor === "pci",
+        // the typed control (formControl), only for a described setting: a plain default keeps the text field
+        property: described ? properties?.[elem] : undefined,
       });
       return acc;
     }, []);
@@ -187,7 +205,10 @@ export const bundle = () => {
 
     const callbacks = `${configValues
       .map((cv) => {
-        return `${cv.name} : function(interaction, value){
+        // a checkbox gives true/false; the PCI gets "true"/"false", as from a data- attribute
+        const toText = cv.property?.editor === "boolean" ? `
+        value = String(value === true || value === 'true');` : "";
+        return `${cv.name} : function(interaction, value){${toText}
         //update the pci property value:
         interaction.prop('${cv.name}', value);
 
@@ -235,25 +256,12 @@ export const bundle = () => {
       outputDirectoryTemp,
       "interaction/creator/tpl/propertiesForm.tpl"
     );
+    const firstManaged = configValues.find((cv) => cv.managed);
     const template = `${configValues
       .map((cv) => {
-        const capitalizedName =
-          cv.name.charAt(0).toUpperCase() + cv.name.slice(1);
-        return `<label for="${cv.name}">{{__ "${capitalizedName}"}}</label>
-        <span class="icon-help tooltipstered" data-tooltip="~ .tooltip-content:first" data-tooltip-theme="info"></span>
-        <span class="tooltip-content">{{__ "${capitalizedName}"}}</span>
-            <input type="text"
-               name="${cv.name}"
-               type="${
-                 cv.type === "string"
-                   ? "text"
-                   : cv.type === "number"
-                   ? "number"
-                   : "text"
-               }"
-               value="{{${cv.name}}}"
-               placeholder="e.g. ${replaceAll(cv.defaultValue, '"', "")}"
-               data-validate="${cv.optional ? "" : "$notEmpty"};">`;
+        // the authoring mode's button goes above the first setting the PCI fills itself
+        const button = cv === firstManaged ? authoringButton(packageData) : "";
+        return `${button}${cv.property ? formControl(cv) : plainControl(cv)}`;
       })
       .join("\r\n")}
 `;
@@ -262,12 +270,50 @@ export const bundle = () => {
       `<!-- ##_HTML_CONTROLS_## -->`,
       template
     );
+
+    // name → editor of the typed controls that start from the property (see creatorControls.fragment.js)
+    const typed = configValues.filter((cv) => cv.property && !["hidden", "pci"].includes(cv.property.editor));
+    if (typed.length) {
+      controlsOptions = Object.fromEntries(typed.map((cv) => [cv.name, controlEditor(cv.property.editor)]));
+    }
+
+    if (firstManaged) {
+      authoringOptions = {
+        properties: configValues.filter((cv) => cv.managed).map((cv) => cv.name),
+        settings: configValues.map((cv) => cv.name),
+        width: packageData.config.tspci.authoring?.width,
+        height: packageData.config.tspci.authoring?.height,
+      };
+    }
   } else {
     console.warn(
       "Create a config.json with properties to generate a TAO config"
     );
   }
 
+  // Typed controls and authoring mode: Question.js gets their code only when config.json asks for them. Without it the
+  // marker lines go, so the file is exactly what it was before either existed.
+  const questionFile = path.join(outputDirectoryTemp, "interaction/creator/widget/states/Question.js");
+  const fragment = (file, marker, options) =>
+    options
+      ? fs
+          .readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), file), "utf8")
+          .replace(`'${marker}'`, () => JSON.stringify(options))
+          .replace(/\s+$/, "")
+      : "";
+  fs.writeFileSync(
+    questionFile,
+    fs
+      .readFileSync(questionFile, "utf8")
+      .replace(/\r?\n[ \t]*\/\/ ##__CONTROLS__##/, () =>
+        fragment("creatorControls.fragment.js", "##__CONTROLS_OPTIONS__##", controlsOptions)
+      )
+      .replace(/\r?\n[ \t]*\/\/ ##__AUTHORING__##/, () =>
+        fragment("creatorAuthoring.fragment.js", "##__AUTHORING_OPTIONS__##", authoringOptions)
+      ),
+    "utf8"
+  );
+
   // copy specific files
   if (fs.existsSync(path.join(PACKAGE_ROOT_PATH, "tao_pci"))) {
     copyDirectoryRecursiveSync(
@@ -353,7 +399,8 @@ export const bundle = () => {
 function replace_string_in_file(filename, to_replace, replace_with) {
   var data = fs.readFileSync(filename, "utf8");
 
-  var result = data.replace(new RegExp(to_replace, "g"), replace_with);
+  // a function, so a $ in a label or default ("$&", "$'") is not a replacement pattern
+  var result = data.replace(new RegExp(to_replace, "g"), () => replace_with);
   fs.writeFileSync(filename, result, "utf8");
 }
 
@@ -411,6 +458,132 @@ function addDirectoryToZip(zipFile, rootDir, currentDir) {
   }
 }
 
+// The button that opens the authoring mode: config.tspci.authoring.label (a text, or one per language, of which
+// TAO's {{__}} gets the English one), else "Configure…".
+function authoringButton(packageData) {
+  const text = readable(packageData.config.tspci.authoring?.label) || "Configure…";
+  return `<div><button type="button" class="btn-info small" data-pci-authoring>{{__ "${String(text).replace(/["\\{}]/g, "")}"}}</button></div>
+`;
+}
+
+// A text given per language (a label, a hint): the English one, as TAO's own strings are, else the first.
+function readable(text) {
+  return typeof text === "string" ? text : text?.en ?? Object.values(text ?? {})[0];
+}
+
+// The properties of the authoring descriptor, from buildDescriptor in the project's @citolab/tspci, so TAO reads the
+// editor hints exactly as the build does. An older tspci without it: no typed controls, every setting a text field.
+async function describedProperties(projectRoot, packageData, config) {
+  let authoring;
+  try {
+    const file = createRequire(path.join(projectRoot, "package.json")).resolve("@citolab/tspci/src/authoring.js");
+    authoring = await import(pathToFileURL(file).href);
+  } catch {
+    console.warn("@citolab/tspci has no authoring descriptor (src/authoring.js): TAO's form gets text fields only");
+    return null;
+  }
+  return authoring.buildDescriptor(packageData, config).descriptor.properties;
+}
+
+// Text in the form template: as HTML, in an element or a quoted attribute, and without anything Handlebars reads
+// ({{ }} and the backslash that escapes them), since a label or a default is the PCI developer's text, not template.
+function escapeHtml(value) {
+  const entities = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;", "{": "&#123;", "}": "&#125;", "\\": "&#92;" };
+  return String(value).replace(/[&<>"'{}\\]/g, (c) => entities[c]);
+}
+
+// The editors creatorControls.fragment.js treats differently; the rest start from the property as text.
+function controlEditor(editor) {
+  return ["boolean", "enum", "color", "colorList"].includes(editor) ? editor : "text";
+}
+
+// A setting given as a plain default: the text field it always had (now with one type attribute: number for a whole
+// number, which TAO's validation passes to the change callback like a text field).
+function plainControl(cv) {
+  const capitalizedName = cv.name.charAt(0).toUpperCase() + cv.name.slice(1);
+  return `<label for="${cv.name}">{{__ "${capitalizedName}"}}</label>
+        <span class="icon-help tooltipstered" data-tooltip="~ .tooltip-content:first" data-tooltip-theme="info"></span>
+        <span class="tooltip-content">{{__ "${capitalizedName}"}}</span>
+            <input type="${cv.type === "number" ? "number" : "text"}"
+               name="${cv.name}"
+               value="{{${cv.name}}}"
+               placeholder="e.g. ${replaceAll(cv.defaultValue, '"', "")}"
+               data-validate="${cv.optional ? "" : "$notEmpty"};">`;
+}
+
+// A described setting: the control of its editor, with its label and its hint as the tooltip. TAO's formElement
+// passes changes of text fields (through its validation), selects, checkboxes and hidden fields to the change
+// callbacks; the colour pickers write the setting's hidden field (creatorControls.fragment.js).
+function formControl(cv) {
+  const property = cv.property;
+  const name = escapeHtml(cv.name);
+  const label = escapeHtml(readable(property.label) || cv.name.charAt(0).toUpperCase() + cv.name.slice(1));
+  const tooltip = `<span class="icon-help tooltipstered" data-tooltip="~ .tooltip-content:first" data-tooltip-theme="info"></span>
+        <span class="tooltip-content">${escapeHtml(readable(property.hint) || readable(property.label) || label)}</span>`;
+  const header = `<label for="${name}">${label}</label>
+        ${tooltip}`;
+  const value = `{{${cv.name}}}`;
+  const placeholder = property.default === "" ? "" : ` placeholder="e.g. ${escapeHtml(property.default)}"`;
+  const range = ["min", "max", "step"]
+    .filter((key) => property[key] !== undefined && property[key] !== null && property[key] !== "")
+    .map((key) => ` ${key}="${escapeHtml(property[key])}"`)
+    .join("");
+  switch (property.editor) {
+    case "hidden":
+      return "";
+    case "boolean":
+      return `<label>
+            <input type="checkbox" name="${name}" value="true">
+            <span class="icon-checkbox"></span>
+            ${label}
+        </label>
+        ${tooltip}`;
+    case "enum":
+      if (!property.options?.length) return formControl({ ...cv, property: { ...property, editor: "text" } });
+      return `${header}
+            <select name="${name}" class="select2" data-has-search="false">${(property.options ?? [])
+              .map((option) => {
+                const text = readable(option.label) || option.value;
+                return `
+                <option value="${escapeHtml(option.value)}">${escapeHtml(text)}</option>`;
+              })
+              .join("")}
+            </select>`;
+    case "integer":
+    case "number":
+      return `${header}
+            <input type="number" name="${name}" value="${value}"${range}${range.includes(" step=") ? "" : property.editor === "integer" ? ' step="1"' : ' step="any"'}${placeholder} data-validate=";">`;
+    case "textarea":
+      return `${header}
+            <textarea name="${name}" rows="4"${placeholder}>${value}</textarea>`;
+    // min-width:0, as TAO's creator gives a colour input a min-inline-size of 150px
+    case "color":
+      return `${header}
+            <span data-tspci-color="${name}" style="display:flex;align-items:center;gap:6px">
+                <input type="color" aria-label="${label}" style="width:44px;min-width:0;height:28px;padding:0;flex:none">
+                <input type="text" aria-label="${label} (hex)" placeholder="#rrggbb" maxlength="7" style="flex:1;min-width:0">
+            </span>
+            <input type="hidden" name="${name}" value="${value}">`;
+    case "colorList":
+      return `${header}
+            <span data-tspci-color-list="${name}" style="display:block">
+                <span data-tspci-items style="display:flex;flex-wrap:wrap;gap:6px;margin-bottom:6px"></span>
+                <span data-tspci-item-template hidden>
+                    <span style="display:inline-flex;align-items:center;gap:2px">
+                        <input type="color" style="width:36px;min-width:0;height:28px;padding:0">
+                        <button type="button" class="btn-default small" title="{{__ "Remove colour"}}" style="padding:0 6px"><span class="icon-bin"></span></button>
+                    </span>
+                </span>
+                <button type="button" class="btn-info small" data-tspci-add><span class="icon-add"></span>{{__ "Add a colour"}}</button>
+            </span>
+            <input type="hidden" name="${name}" value="${value}">`;
+    default:
+      // text, pci (the "Configure…" button above it fills it) and an editor this packager does not know
+      return `${header}
+            <input type="text" name="${name}" value="${value}"${placeholder} data-validate=";">`;
+  }
+}
+
 function replaceAll(str, find, replace) {
   return str.replace(new RegExp(find, "g"), replace);
 }

package/src/creatorAuthoring.fragment.js

@@ -0,0 +1,185 @@
+
+      // Authoring mode (@citolab/tspci AUTHORING.md): the "Configure…" button opens the PCI's own editor for the
+      // settings it manages (editor "pci"). The creator runs in TAO's page with RequireJS, so the runtime module is
+      // required and getAuthoringInstance is called directly; no iframe and no messages.
+      var authoring = '##__AUTHORING_OPTIONS__##';
+      // A managed setting is usually JSON. TAO turns a JSON property into an object when it loads a saved item, so
+      // read it back as text: for the PCI, and for the setting's text field (which would show "[object Object]").
+      var settingText = function(value){
+          return value !== null && typeof value === 'object' ? JSON.stringify(value) : String(value);
+      };
+      authoring.settings.forEach(function(name){
+          var value = interaction.prop(name);
+          if (value !== undefined && value !== null) {
+              $form.find('[name="' + name + '"]').val(settingText(value));
+          }
+      });
+      $form.find('[data-pci-authoring]').on('click', function(){
+          require(['jquery', 'i18n'], function($, __){
+              openAuthoring($, __);
+          });
+      });
+
+      function openAuthoring($, __){
+          if ($('.tspci-authoring').length) {
+              return;
+          }
+          var instance;
+          var closed = false;
+          var $dialog = $('<div class="tspci-authoring">' +
+              '<div class="tspci-authoring-pci"></div>' +
+              '<div class="feedback-error tspci-authoring-problems"></div>' +
+              '<div class="tspci-authoring-actions">' +
+              '<button type="button" class="btn-default small" data-action="cancel"></button> ' +
+              '<button type="button" class="btn-info small" data-action="done" disabled></button>' +
+              '</div></div>');
+          var $pci = $dialog.find('.tspci-authoring-pci').css({
+              width: authoring.width ? authoring.width + 'px' : '100%',
+              height: authoring.height ? authoring.height + 'px' : 'auto',
+              maxWidth: '100%',
+              maxHeight: '70vh',
+              overflow: 'auto'
+          });
+          var $problems = $dialog.find('.tspci-authoring-problems').hide();
+          var $done = $dialog.find('[data-action="done"]').text(__('Done'));
+          $dialog.find('[data-action="cancel"]').text(__('Cancel'));
+          $dialog.find('.tspci-authoring-actions').css({ marginTop: '12px', textAlign: 'right' });
+
+          var showProblems = function(problems){
+              $problems.empty().append(problems.map(function(problem){
+                  return $('<div>').text(problem);
+              })).show();
+          };
+          // every way out (Cancel, Done, the close button, Escape) ends here
+          var cleanUp = function(){
+              closed = true;
+              if (instance && typeof instance.destroy === 'function') {
+                  instance.destroy();
+              }
+              instance = null;
+              $dialog.remove();
+          };
+          var close = openDialog($, $dialog, startPci, cleanUp);
+
+          $dialog.find('[data-action="cancel"]').on('click', close);
+          $done.on('click', function(){
+              if (!instance) {
+                  return;
+              }
+              var problems = typeof instance.validate === 'function' ? instance.validate() || [] : [];
+              if (problems.length) {
+                  showProblems(problems);
+                  return;
+              }
+              var config = instance.getConfig() || {};
+              // only the managed properties are written, as strings, the same way the form fields write them
+              authoring.properties.forEach(function(name){
+                  if (Object.prototype.hasOwnProperty.call(config, name)) {
+                      var value = String(config[name]);
+                      interaction.prop(name, value);
+                      interaction.triggerPci(name, value);
+                      $form.find('[name="' + name + '"]').val(value);
+                  }
+              });
+              close();
+          });
+
+          // the PCI renders once the dialog is in the page, so it can measure itself
+          function startPci(){
+              require(['##typeIdentifier##/interaction/runtime/js/index'], function(pciModule){
+                  if (closed) {
+                      return;
+                  }
+                  // the tspci bundle returns the registered PCI; else take what it registered with TAO's context
+                  var pci = pciModule && typeof pciModule.getAuthoringInstance === 'function'
+                      ? pciModule
+                      : (window._pciHooks || {})['##typeIdentifier##'];
+                  if (!pci || typeof pci.getAuthoringInstance !== 'function') {
+                      showProblems([__('This version of the PCI has no authoring mode. Use the fields below the button instead.')]);
+                      return;
+                  }
+                  var properties = {};
+                  authoring.settings.forEach(function(name){
+                      var value = interaction.prop(name);
+                      if (value !== undefined && value !== null) {
+                          properties[name] = settingText(value);
+                      }
+                  });
+                  try {
+                      var returned = pci.getAuthoringInstance($pci[0], {
+                          properties: properties,
+                          language: document.documentElement.getAttribute('lang') || navigator.language,
+                          onready: function(ready){
+                              instance = ready;
+                              $done.prop('disabled', false);
+                          },
+                          // what Done said was missing may be fixed now; Done checks again
+                          onchange: function(){
+                              $problems.hide().empty();
+                          }
+                      });
+                      if (returned) {
+                          instance = returned;
+                          $done.prop('disabled', false);
+                      }
+                  } catch (e) {
+                      showProblems([String(e && e.message || e)]);
+                  }
+              }, function(e){
+                  showProblems([String(e && e.message || e)]);
+              });
+          }
+      }
+
+      // TAO's modal (ui/modal) when the creator has it, else a plain overlay. Calls onOpened once the dialog is in
+      // the page, and returns the function that closes it.
+      function openDialog($, $dialog, onOpened, onClosed){
+          var closed = false;
+          var whenClosed = function(){
+              if (!closed) {
+                  closed = true;
+                  onClosed();
+              }
+          };
+          var close = function(){
+              whenClosed();
+          };
+          require(['ui/modal'], function(){
+              if (closed) {
+                  return;
+              }
+              $dialog.addClass('modal').appendTo('body').modal({
+                  width: Math.min((authoring.width || 640) + 48, Math.round(window.innerWidth * 0.96))
+              });
+              $dialog.on('closed.modal', function(){
+                  $dialog.modal('destroy');
+                  whenClosed();
+              });
+              close = function(){
+                  $dialog.modal('close');
+              };
+              onOpened();
+          }, function(){
+              var $overlay = $('<div class="tspci-authoring-overlay">').css({
+                  position: 'fixed', top: 0, right: 0, bottom: 0, left: 0, zIndex: 100000,
+                  background: 'rgba(0,0,0,.5)', display: 'flex', alignItems: 'center', justifyContent: 'center'
+              });
+              $dialog.css({ background: '#fff', padding: '24px', maxWidth: '96vw', maxHeight: '96vh', overflow: 'auto' });
+              $overlay.append($dialog).appendTo('body');
+              var onKey = function(e){
+                  if (e.key === 'Escape') {
+                      close();
+                  }
+              };
+              $(document).on('keydown', onKey);
+              close = function(){
+                  $(document).off('keydown', onKey);
+                  $overlay.remove();
+                  whenClosed();
+              };
+              onOpened();
+          });
+          return function(){
+              close();
+          };
+      }

package/src/creatorControls.fragment.js

@@ -0,0 +1,105 @@
+
+      // Typed settings (the editor hints in config.json, see @citolab/tspci AUTHORING.md). Runs before initWidget, so
+      // TAO's select2 starts from the right option. TAO turns a property that looks like JSON (400, true) into a number
+      // or boolean when it loads a saved item, and the `||` above drops 0 and false, so every control starts from the
+      // property itself, as text.
+      var controls = '##__CONTROLS_OPTIONS__##';
+      var propertyText = function(value){
+          return value !== null && typeof value === 'object' ? JSON.stringify(value) : String(value);
+      };
+      var $setting = function(name){
+          return $form.find(':input').filter(function(){
+              return this.name === name;
+          });
+      };
+      Object.keys(controls).forEach(function(name){
+          var value = interaction.prop(name);
+          if (value === undefined || value === null) {
+              return;
+          }
+          value = propertyText(value);
+          var $input = $setting(name);
+          if (controls[name] === 'boolean') {
+              $input.prop('checked', value === 'true');
+              return;
+          }
+          // a value that is not one of the options (set elsewhere) is shown as it is, not as the first option
+          if ($input.is('select') && !$input.find('option').filter(function(){ return this.value === value; }).length) {
+              $input.append($input.find('option').first().clone().val(value).text(value));
+          }
+          $input.val(value);
+      });
+
+      // Colour pickers write through the setting's hidden field: its change event reaches the callbacks below,
+      // which set the property and tell the PCI, as for any other field.
+      var hexColor = function(value){
+          var hex = String(value).trim();
+          if (/^#[0-9a-f]{3}$/i.test(hex)) {
+              hex = '#' + hex[1] + hex[1] + hex[2] + hex[2] + hex[3] + hex[3];
+          }
+          // <input type="color"> only takes #rrggbb; another colour ("red") shows as black until it is picked
+          return /^#[0-9a-f]{6}$/i.test(hex) ? hex.toLowerCase() : '#000000';
+      };
+      var writeSetting = function($hidden, value){
+          if ($hidden.val() !== value) {
+              $hidden.val(value).trigger('change');
+          }
+      };
+      var $colors = $form.find('[data-tspci-color]');
+      $colors.each(function(i){
+          var $color = $colors.eq(i);
+          var $hidden = $setting($color.attr('data-tspci-color'));
+          var $picker = $color.find('input[type="color"]').val(hexColor($hidden.val()));
+          var $hex = $color.find('input[type="text"]').val($hidden.val());
+          $picker.on('input', function(){
+              $hex.val($picker.val());
+          });
+          $picker.on('change', function(){
+              $hex.val($picker.val());
+              writeSetting($hidden, $picker.val());
+          });
+          $hex.on('input change', function(){
+              var value = $hex.val().trim();
+              if (/^#([0-9a-f]{3}){1,2}$/i.test(value)) {
+                  $picker.val(hexColor(value));
+                  writeSetting($hidden, value);
+              }
+          });
+      });
+      var $colorLists = $form.find('[data-tspci-color-list]');
+      $colorLists.each(function(i){
+          var $list = $colorLists.eq(i);
+          var $hidden = $setting($list.attr('data-tspci-color-list'));
+          var $items = $list.find('[data-tspci-items]');
+          var $template = $list.find('[data-tspci-item-template]');
+          var $prototype = $template.children().first().detach();
+          $template.remove();
+          var colors = $hidden.val().split(',').map(function(color){ return color.trim(); }).filter(Boolean);
+          var write = function(){
+              writeSetting($hidden, colors.join(', '));
+          };
+          var render = function(){
+              $items.empty();
+              colors.forEach(function(color, index){
+                  var $item = $prototype.clone();
+                  $item.find('input[type="color"]').val(hexColor(color)).attr('title', color).on('change', function(){
+                      colors[index] = this.value;
+                      this.title = this.value;
+                      write();
+                  });
+                  // the PCI needs at least one colour
+                  $item.find('button').prop('disabled', colors.length < 2).on('click', function(){
+                      colors.splice(index, 1);
+                      render();
+                      write();
+                  });
+                  $items.append($item);
+              });
+          };
+          $list.find('[data-tspci-add]').on('click', function(){
+              colors.push(colors.length ? hexColor(colors[colors.length - 1]) : '#000000');
+              render();
+              write();
+          });
+          render();
+      });

package/toa_pci_default/interaction/creator/widget/states/Question.js

@@ -32,6 +32,7 @@ define([
           identifier : interaction.attr('responseIdentifier'),
           // ##__SET_VARIABLES__##
       }));
+      // ##__CONTROLS__##
 
       //init form javascript
       formElement.initWidget($form);
@@ -44,6 +45,7 @@ define([
           },
           // ##__CALLBACK__##
       });
+      // ##__AUTHORING__##
 
   };