@examplary/pci-runtime 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,68 @@
+# Examplary PCI runtime
+
+A PCI (Portable Custom Interaction) runtime for Examplary question type components. This package provides the necessary runtime environment to load Examplary custom question types as QTI 3.0 PCI components.
+
+## Usage
+
+Define a PCI QTI item:
+
+```xml
+<qti-assessment-item
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns="http://www.imsglobal.org/xsd/imsqtiasi_v3p0"
+  xsi:schemalocation="http://www.imsglobal.org/xsd/imsqtiasi_v3p0 https://purl.imsglobal.org/spec/qti/v3p0/schema/xsd/imsqti_asiv3p0_v1p0.xsd"
+  identifier="question-1"
+  title="Sample Question"
+  xml:lang="en-US"
+  adaptive="false"
+  time-dependent="false"
+  tool-name="Examplary"
+  tool-version="1.0.0"
+>
+  <qti-response-declaration identifier="RESPONSE" cardinality="single" base-type="string" />
+  <qti-response-processing template="https://purl.imsglobal.org/spec/qti/v3p0/rptemplates/match_correct" />
+
+  <qti-item-body>
+    <p>Hello, world!</p>
+
+    <qti-portable-custom-interaction
+      response-identifier="RESPONSE"
+      module="my-question-type"
+      custom-interaction-type-identifier="urn:fdc:examplary.ai:pci:com.example.my-question-type"
+      data-question="{... JSON data ...}"
+      class="examplary-pci-runtime"
+    >
+       <qti-interaction-markup></qti-interaction-markup>
+    </qti-portable-custom-interaction>
+  </qti-item-body>
+</qti-assessment-item>
+```
+
+Make sure to set up a module mapping file (usually called `modules/module_resolution.js` with identifier `pci_module_resolution`) to map the `module` attribute to the actual JavaScript module that implements the question type:
+
+```js
+{
+    "waitSeconds": 60,
+    "paths": {
+        "examplaryPciRuntime": "modules/runtime.js",
+        "my-question-type": "modules/my-question-type.js"
+    }
+}
+```
+
+Where `modules/runtime.js` is a copy of the [runtime code](https://unpkg.com/@examplary/pci-runtime), and `modules/my-question-type.js` is your custom question type implementation:
+
+```js
+define(['qtiCustomInteractionContext', 'examplaryPciRuntime'], function (qtiCustomInteractionContext, examplaryPciRuntime) {
+    return examplaryPciRuntime.register({
+        qtiCustomInteractionContext,
+        id: 'com.example.my-question-type',
+        language: 'en',
+        translations: {
+            'placeholder': 'Type your answer here...'
+        },
+        component: '(assessment component compiled JS here)',
+        stylesheet: '(assessment component compiled CSS here, optional)'
+    });
+});
+```

package/package.json

@@ -2,7 +2,7 @@
   "name": "@examplary/pci-runtime",
   "type": "module",
   "packageManager": "yarn@4.8.1",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "PCI runtime for Examplary question type components.",
   "scripts": {
     "build": "node ./scripts/build.js",
@@ -11,9 +11,12 @@
     "release": "semantic-release -e semantic-release-monorepo"
   },
   "devDependencies": {
+    "@citolab/tspci": "^2.6.5",
+    "@examplary/ui": "workspace:^",
     "esbuild": "^0.27.2",
     "typescript": "^5.9.3",
-    "vite": "^7.3.0"
+    "vite": "^7.3.0",
+    "zustand": "^5.0.9"
   },
   "main": "./public/dist/runtime.js",
   "files": [
@@ -23,9 +26,5 @@
   "author": {
     "name": "Examplary AI",
     "email": "hi@examplary.ai"
-  },
-  "dependencies": {
-    "@examplary/ui": "workspace:^",
-    "zustand": "^5.0.9"
   }
 }

package/public/dist/runtime.js

@@ -1,4 +1,4 @@
-define(['qtiCustomInteractionContext'], function(qtiCustomInteractionContext) {
+define(function() {
 "use strict";
 var __export__ = (() => {
   var __create = Object.create;
@@ -1662,14 +1662,14 @@ var __export__ = (() => {
           return x5 === y3 && (0 !== x5 || 1 / x5 === 1 / y3) || x5 !== x5 && y3 !== y3;
         }
         "undefined" !== typeof __REACT_DEVTOOLS_GLOBAL_HOOK__ && "function" === typeof __REACT_DEVTOOLS_GLOBAL_HOOK__.registerInternalModuleStart && __REACT_DEVTOOLS_GLOBAL_HOOK__.registerInternalModuleStart(Error());
-        var React72 = require_react(), shim = require_shim(), objectIs = "function" === typeof Object.is ? Object.is : is2, useSyncExternalStore3 = shim.useSyncExternalStore, useRef32 = React72.useRef, useEffect37 = React72.useEffect, useMemo18 = React72.useMemo, useDebugValue3 = React72.useDebugValue;
+        var React72 = require_react(), shim = require_shim(), objectIs = "function" === typeof Object.is ? Object.is : is2, useSyncExternalStore3 = shim.useSyncExternalStore, useRef32 = React72.useRef, useEffect37 = React72.useEffect, useMemo19 = React72.useMemo, useDebugValue3 = React72.useDebugValue;
         exports.useSyncExternalStoreWithSelector = function(subscribe, getSnapshot, getServerSnapshot, selector, isEqual) {
           var instRef = useRef32(null);
           if (null === instRef.current) {
             var inst = { hasValue: false, value: null };
             instRef.current = inst;
           } else inst = instRef.current;
-          instRef = useMemo18(
+          instRef = useMemo19(
             function() {
               function memoizedSelector(nextSnapshot) {
                 if (!hasMemo) {
@@ -19831,7 +19831,7 @@ var __export__ = (() => {
   // src/runtime.tsx
   var runtime_exports = {};
   __export(runtime_exports, {
-    default: () => runtime_default
+    register: () => register
   });
   var import_react52 = __toESM(require_react(), 1);
 
@@ -96010,70 +96010,89 @@ import "https://unpkg.com/@cortex-js/compute-engine?module"`), '["Error", "compu
 
   // src/runtime.tsx
   var import_client5 = __toESM(require_client(), 1);
-  var AssessmentComponent = null;
-  if (typeof EXAMPLARY_QUESTION_TYPE_ID === "undefined" || typeof EXAMPLARY_QUESTION_TYPE_COMPONENT === "undefined") {
-    throw new Error(
-      "Missing required global variables for Examplary PCI runtime."
-    );
-  }
-  var runtime = {
-    typeIdentifier: `urn:fdc:examplary.ai:pci:${EXAMPLARY_QUESTION_TYPE_ID}`,
-    _baseElement: null,
-    _store: null,
-    _state: {},
-    _config: {},
-    _question: {},
-    _onReadyCalled: false,
-    /**
-     * Create a new instance of this portable custom interaction.
-     * Will be called by the qtiCustomInteractionContext.
-     */
-    getInstance: function(dom, configuration, state) {
-      const newInstance = Object.assign({}, this);
-      newInstance._init = newInstance._init.bind(newInstance);
-      newInstance._init(dom, configuration, state);
-      return newInstance;
-    },
-    /**
-     * Initialize this PCI instance with the provided DOM element,
-     */
-    _init: function(dom, configuration, state) {
-      this._baseElement = dom;
-      const uid = "tap-" + Math.floor(Math.random() * 1e5);
-      dom.setAttribute("data-uid", uid);
-      this._config = configuration;
-      const json = configuration.properties.examplarySettings || "{}";
-      this._question = JSON.parse(json);
-      console.log("[PCI-Examplary] init", { state, configuration });
-      if (state) {
-        this._state = JSON.parse(state);
-      }
-      this._store = create((set2) => ({
-        answer: this._state?.answer || null,
-        saveAnswer: (answer) => set2({
-          answer
-        })
-      }));
-      this.oncompleted = this.oncompleted.bind(this);
-      this._loadComponent();
-      return this;
-    },
-    _loadComponent: async function() {
-      if (!AssessmentComponent) {
-        AssessmentComponent = await evalComponent(
-          EXAMPLARY_QUESTION_TYPE_COMPONENT
-        );
+  var register = ({
+    qtiCustomInteractionContext,
+    id: id2,
+    component,
+    language,
+    translations,
+    stylesheet
+  }) => {
+    if (!id2 || !component) {
+      throw new Error(
+        "Missing required parameters 'id' or 'component' for Examplary PCI runtime."
+      );
+    }
+    let AssessmentComponent = null;
+    class ExamplaryPci {
+      typeIdentifier;
+      dom = null;
+      shadowRoot = null;
+      config = null;
+      _question = null;
+      _state = null;
+      _onReadyCalled = false;
+      debounceTimeout = null;
+      store = null;
+      /**
+       * Set correct type identifier and register PCI,
+       * if context is provided.
+       */
+      constructor() {
+        this.typeIdentifier = `urn:fdc:examplary.ai:pci:${id2}`;
+        if (qtiCustomInteractionContext) {
+          qtiCustomInteractionContext.register(this);
+        }
       }
-      (() => {
-        if ("_context" in AssessmentComponent) {
-          const context = AssessmentComponent._context;
-          for (const dep in context) {
-            globalThis[dep] = context[dep];
+      /**
+       * Create a new instance of this portable custom interaction.
+       * Will be called by the qtiCustomInteractionContext.
+       */
+      getInstance(dom, config, state) {
+        const json = config.properties.examplarySettings || "{}";
+        const question = JSON.parse(json);
+        this.config = config;
+        this._state = state ? JSON.parse(state) : null;
+        this.store = create()((set2) => ({
+          answer: this._state?.answer || null,
+          question,
+          saveAnswer: (answer) => {
+            set2({ answer });
+            this.interactionChanged();
+          }
+        }));
+        if (this.config.boundTo && Object.keys(this.config.boundTo).length > 0) {
+          const responseIdentifier = Object.keys(this.config.boundTo)[0];
+          const response = this.config.boundTo[responseIdentifier];
+          if (response && response.base !== null) {
+            this.setResponse(response);
           }
         }
-        const stylesheet = typeof EXAMPLARY_QUESTION_TYPE_STYLESHEET === "undefined" ? "" : EXAMPLARY_QUESTION_TYPE_STYLESHEET;
-        const shadowRoot = this._baseElement.attachShadow({ mode: "open" });
-        shadowRoot.innerHTML = `
+        if (!dom) {
+          throw new Error("No DOM Element provided");
+        }
+        this.dom = dom;
+        this.shadowRoot = dom.shadowRoot || dom.attachShadow({ mode: "open" });
+        this.render();
+        return this;
+      }
+      /**
+       * Render the PCI component inside the provided DOM element.
+       */
+      async render() {
+        if (!AssessmentComponent) {
+          AssessmentComponent = await evalComponent(
+            component
+          );
+        }
+        (() => {
+          if ("_context" in AssessmentComponent) {
+            const context = AssessmentComponent._context;
+            for (const dep in context) {
+              globalThis[dep] = context[dep];
+            }
+          }
+          this.shadowRoot.innerHTML = `
         <style>
           
     @layer modules_theme, theme, modules_base, base, modules_components, components, modules_utilities, utilities; 
@@ -100304,106 +100323,160 @@ body {
         </style>
         <div class="examplary-component-root"></div>
       `;
-        const root = shadowRoot.querySelector(".examplary-component-root");
-        const AssessmentCoreComponent = () => {
-          const answer = this._store((state) => state.answer);
-          const saveAnswer = this._store((state) => state.saveAnswer);
-          (0, import_react52.useEffect)(() => {
-            if (!this._onReadyCalled) {
-              this._onReadyCalled = true;
-              if (this._config.onready) {
-                this._config.onready(this, this.getState());
-              }
-            }
-          }, []);
-          return (
-            // @ts-expect-error api
-            /* @__PURE__ */ React.createElement(
-              AssessmentComponent,
-              {
-                question: this._question,
-                isPreview: false,
-                answer,
-                saveAnswer,
-                api: null,
-                t: (key) => EXAMPLARY_QUESTION_TYPE_TRANSLATIONS[key] || key,
-                i18n: { language: EXAMPLARY_QUESTION_TYPE_LANGUAGE || "en" }
-              }
-            )
+          const root = this.shadowRoot.querySelector(
+            ".examplary-component-root"
           );
+          const AssessmentCoreComponent = () => {
+            const answer = this.store((state) => state.answer);
+            const saveAnswer = this.store((state) => state.saveAnswer);
+            (0, import_react52.useEffect)(() => {
+              if (this.config.onready) {
+                if (!this._onReadyCalled) {
+                  this._onReadyCalled = true;
+                  this.config.onready(this, this.getState());
+                }
+              }
+            }, []);
+            const translate = (0, import_react52.useCallback)((key) => {
+              return translations?.[key] || key;
+            }, []);
+            const i18n = (0, import_react52.useMemo)(() => ({ language: language || "en" }), []);
+            return (
+              // @ts-expect-error api
+              /* @__PURE__ */ React.createElement(
+                AssessmentComponent,
+                {
+                  question: this._question,
+                  isPreview: false,
+                  answer,
+                  saveAnswer,
+                  api: null,
+                  t: translate,
+                  i18n
+                }
+              )
+            );
+          };
+          (0, import_client5.createRoot)(root).render(/* @__PURE__ */ React.createElement(AssessmentCoreComponent, null));
+        })();
+      }
+      /**
+       * Get the output response for this PCI instance.
+       *
+       * This will be requested by the Delivery System when
+       * it needs to collect the responses.
+       */
+      getResponse() {
+        if (!this.store?.getState().answer) {
+          return void 0;
+        }
+        let answerValue = this.store?.getState().answer?.value || "";
+        if (Array.isArray(answerValue)) {
+          answerValue = answerValue.join(",");
+        }
+        return {
+          base: {
+            string: answerValue
+          }
         };
-        (0, import_client5.createRoot)(root).render(/* @__PURE__ */ React.createElement(AssessmentCoreComponent, null));
-      })();
-    },
-    /**
-     * Get the output response for this PCI instance.
-     */
-    getResponse: function() {
-      console.log(`[PCI-Examplary] getResponse`);
-      if (!this._store?.getState().answer) {
-        return void 0;
       }
-      let answerValue = this._store?.getState().answer?.value || "";
-      if (Array.isArray(answerValue)) {
-        answerValue = answerValue.join(",");
+      /**
+       * Returns whether the current response is valid.
+       */
+      checkValidity() {
+        return !!this.store?.getState().answer;
       }
-      return {
-        base: {
-          string: answerValue
+      /**
+       * The current state of this PCI. May be passed to getInstance
+       * to later restore this PCI instance.
+       */
+      getState() {
+        return JSON.stringify({
+          answer: this.store?.getState().answer || null
+        });
+      }
+      /**
+       * Restore a previous state of the PCI instance.
+       */
+      setState(value) {
+        if (value) {
+          this._state = JSON.parse(value);
+          this.store?.setState({
+            answer: this._state.answer || null
+          });
         }
+      }
+      /**
+       * Restore the response value for this PCI instance.
+       */
+      setResponse(value) {
+        const answerValue = value?.base?.string || value?.base?.integer || value?.base?.float || value?.base?.boolean || null;
+        this.store?.setState((state) => ({
+          answer: {
+            ...state.answer,
+            value: answerValue
+          }
+        }));
+      }
+      /**
+       * Notify the Delivery System that the response has changed.
+       */
+      interactionChanged = () => {
+        if (this.debounceTimeout) {
+          clearTimeout(this.debounceTimeout);
+        }
+        this.debounceTimeout = setTimeout(() => {
+          const event = {
+            interaction: this,
+            responseIdentifier: this.config.responseIdentifier,
+            valid: this.checkValidity(),
+            value: this.getResponse()
+          };
+          const interactionChangedEvent = new CustomEvent(
+            "qti-interaction-changed",
+            { detail: event }
+          );
+          this.dom?.dispatchEvent(interactionChangedEvent);
+        }, 1e3);
       };
-    },
-    checkValidity: function() {
-      console.log(`[PCI-Examplary] checkValidity`);
-      if (!this._store?.getState().answer) {
-        return false;
+      /**
+       * This will be provided as the oncompleted callback to cleanup
+       * before this PCI is unloaded.
+       *
+       * We don't have any special cleanup to do here.
+       */
+      oncompleted() {
       }
-      return true;
-    },
-    /**
-     * The current state of this PCI. May be passed to getInstance
-     * to later restore this PCI instance.
-     */
-    getState: function() {
-      console.log(`[PCI-Examplary] getState`);
-      return JSON.stringify({
-        answer: this._store?.getState().answer || null
-      });
-    },
-    /**
-     * Restore a previous state of the PCI instance.
-     */
-    setState: function(value) {
-      console.log(`[PCI-Examplary] setState`);
-      if (value) {
-        this._state = JSON.parse(value);
-        this._store?.setState({
-          answer: this._state.answer || null
-        });
+      // ------------------------------------------------
+      // TAO compatibility methods
+      // ------------------------------------------------
+      /**
+       * Called when setting correct response in tao
+       */
+      off() {
       }
-    },
-    setResponse: function(value) {
-      console.log(`[PCI-Examplary] setResponse`, value);
-      const answerValue = value?.base?.string || value?.base?.integer || value?.base?.float || value?.base?.boolean || null;
-      this._store?.setState((state) => ({
-        answer: {
-          ...state.answer,
-          value: answerValue
-        }
-      }));
-    },
-    /**
-     * This will be provided as the oncompleted callback to cleanup
-     * before this PCI is unloaded.
-     */
-    oncompleted: function() {
-      console.log(`[PCI-Examplary] oncompleted`);
+      /**
+       * Called by TAO when binding events?
+       */
+      on(_5) {
+      }
+      /**
+       * Called by TAO for a changed property.
+       */
+      trigger = (event, value) => {
+        this.config.properties[event] = value;
+        this.render();
+      };
+      /**
+       * Reset the response in TAO
+       */
+      resetResponse = () => {
+        this.render();
+        this.store?.setState({ answer: null });
+      };
     }
+    return new ExamplaryPci();
   };
-  if (qtiCustomInteractionContext) {
-    qtiCustomInteractionContext.register(runtime);
-  }
-  var runtime_default = runtime;
   return __toCommonJS(runtime_exports);
 })();
 /*! Bundled license information: