@citolab/tspci 2.12.1 → 2.14.0

package/preset/preact/src/interaction.tsx

@@ -1,45 +1,58 @@
-import { useStore, IStore, Action } from "@citolab/preact-store";
-import { ActionType, StateModel } from "./store";
+import type { PciProperties } from "@citolab/tspci";
+import { IStore, useStore } from "@citolab/preact-store";
+import { useLayoutEffect, useRef, useState } from "preact/hooks";
 import configProps from "./config.json";
-import { useState } from "preact/hooks";
+import { Pie } from "./pie";
+import { Actions, StateModel } from "./store";
+// Images are bundled too: `import logo from "./assets/logo.png"` gives a data URL for <img src={logo} />.
 
-import procenten from "./assets/procenten.png"; // image types are bundled inside the js
+type PropTypes = PciProperties<typeof configProps>;
 
-type PropTypes = typeof configProps;
+type Props = {
+  config: PropTypes;
+  store: IStore<StateModel, Actions>;
+  readOnly: boolean; // review, solution, closed: show the answer, but do not change it
+};
 
-const Interaction = ({ config, dom, store }: { config: PropTypes; dom: Document | ShadowRoot, store: IStore<StateModel> }) => {
-  const state = useStore(store);
-  const [eventHandled, setEventHandled] = useState<boolean>(false);
-  
-  const handleInput = (e: Event) => {
-    if (!eventHandled) {
-      const input = e.target as HTMLInputElement;
-      store.dispatch<{ input: number }>({ type: "SET_INPUT", payload: { input: +input.value } });
-      setEventHandled(true);
-    }
-  };
+/** The interaction itself: Tailwind classes only, styles.css just loads Tailwind (into the shadow root). */
+const Interaction = ({ config, store, readOnly }: Props) => {
+  const { value } = useStore(store); // re-renders when the store changes
+  const input = useRef<HTMLInputElement>(null);
+  const [invalid, setInvalid] = useState(false);
 
-  return <div className="pci-container">
-    <h1 className="title">{config.title}</h1>
-    <div className="body">
-      <img className="body-image" width={config.width} height={+config.height} src={procenten} alt="Percentages visual" />
-    </div>
-    <div className="interaction">
-      <label className="prompt" htmlFor="percentage-input">{config.prompt}</label>
-      <div className="answer-row">
-        <input className="answer-input"
-          id="percentage-input"
+  // aria-invalid tells assistive technology, and the aria-invalid: classes show it with a red outline.
+  useLayoutEffect(() => {
+    setInvalid(value !== "" && !input.current.checkValidity());
+  }, [value]);
+
+  return (
+    <div className="mx-auto flex w-fit max-w-full flex-col items-center gap-4 rounded-2xl border border-slate-200 bg-linear-to-b from-white to-slate-50 px-7 py-6 font-sans text-slate-800 shadow-lg">
+      <h2 className="text-xl font-semibold tracking-tight">{config.title}</h2>
+      <Pie config={config} />
+      {/* htmlFor ties the question to the input: a screen reader reads it, a click on it focuses the input */}
+      <label className="max-w-[32ch] cursor-pointer text-center text-slate-600" htmlFor="answer">
+        {config.question}
+      </label>
+      <div className="flex items-center gap-1.5 text-lg font-semibold">
+        <input
+          ref={input}
+          id="answer"
           type="number"
-          value={state.input}
-          onInput={handleInput}
-          onPaste={() => setEventHandled(false)}
-          onKeyDown={() => setEventHandled(false)}
-          min="0" max="100" />
-        <span className="answer-suffix">%</span>
+          inputMode="numeric"
+          min={0}
+          max={100}
+          step={1}
+          autoComplete="off"
+          value={value}
+          disabled={readOnly}
+          aria-invalid={invalid}
+          onInput={(e) => store.dispatch({ type: "SET_VALUE", payload: { value: e.currentTarget.value } })}
+          className="w-20 rounded-lg border-[1.5px] border-slate-300 bg-white px-2.5 py-2 text-right outline-none transition [appearance:textfield] focus-visible:border-blue-500 focus-visible:ring-3 focus-visible:ring-blue-500/30 aria-invalid:border-rose-600 aria-invalid:ring-3 aria-invalid:ring-rose-600/20 disabled:cursor-not-allowed disabled:bg-slate-100 disabled:text-slate-500 [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none"
+        />
+        <span>%</span>
       </div>
     </div>
-  </div>;
+  );
 };
 
-
 export default Interaction;

package/preset/preact/src/pie.tsx

@@ -0,0 +1,46 @@
+import type { PciProperties } from "@citolab/tspci";
+import configProps from "./config.json";
+
+type PropTypes = PciProperties<typeof configProps>;
+
+/** Settings arrive as strings (they are data- attributes) and an author may type anything: parse and clamp them. */
+const toInt = (value: string, fallback: number, min: number, max: number) => {
+  const n = Number.parseInt(value, 10);
+  return Number.isNaN(n) ? fallback : Math.min(max, Math.max(min, n));
+};
+
+/** A circle of `segments` equal slices, the first `colored` ones filled, clockwise from the top. */
+export const Pie = ({ config }: { config: PropTypes }) => {
+  // the limits match the min/max in config.json
+  const segments = toInt(config.segments, 10, 2, 24);
+  const colored = toInt(config.colored, 0, 0, segments);
+  const size = toInt(config.size, 200, 100, 400);
+  const c = size / 2; // centre
+  const r = c - 4; // leave room for the outline
+  const point = (i: number) => {
+    const angle = -Math.PI / 2 + (2 * Math.PI * i) / segments;
+    return `${(c + r * Math.cos(angle)).toFixed(2)} ${(c + r * Math.sin(angle)).toFixed(2)}`;
+  };
+
+  // role="img" + aria-label: a screen reader reads one description instead of a list of paths.
+  // Translate the label when your items are not in English.
+  return (
+    <svg
+      className="h-auto max-w-full drop-shadow-md"
+      viewBox={`0 0 ${size} ${size}`}
+      width={size}
+      height={size}
+      role="img"
+      aria-label={`A circle in ${segments} equal slices, ${colored} of them coloured`}
+    >
+      {Array.from({ length: segments }, (_, i) => (
+        <path
+          key={i}
+          className={i < colored ? "stroke-white stroke-2" : "fill-slate-200 stroke-white stroke-2"}
+          fill={i < colored ? config.color || "#3b82f6" : undefined}
+          d={`M ${c} ${c} L ${point(i)} A ${r} ${r} 0 0 1 ${point(i + 1)} Z`}
+        />
+      ))}
+    </svg>
+  );
+};

package/preset/preact/src/store.ts

@@ -1,19 +1,17 @@
 import { Store } from "@citolab/preact-store";
 
-export type ActionType = "SET_INPUT" | "RESTORE_STATE";
-export type StateModel = { input: number | undefined };
+/**
+ * The state of the PCI. Every change goes through an action (store.dispatch), and the store keeps the list of actions:
+ * getState() saves both, so a session can be restored, and even replayed (store.replay), action by action.
+ */
+export type StateModel = { value: string }; // the text in the input, also when it is not a number yet
+/** The actions, as { type: payload }: dispatch and addReducer only accept these. */
+export type Actions = { SET_VALUE: { value: string } };
 
-export const initStore = (
-  initialState: StateModel,
-  restoreData?: {
-    state: StateModel;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    actions: { type: string; payload: any; timestamp?: number }[];
-  }
-) => {
-  const store = new Store<StateModel>(initialState, restoreData);
-  store.addReducer<{ input: number | undefined }>("SET_INPUT", (state, { input }) => {
-    return { ...state, input };
-  });
+export const initialState: StateModel = { value: "" };
+
+export const initStore = (state: StateModel = initialState) => {
+  const store = new Store<StateModel, Actions>(state);
+  store.addReducer("SET_VALUE", (current, { value }) => ({ ...current, value }));
   return store;
 };

package/preset/tailwind/src/styles.css

@@ -1,30 +1,7 @@
+/*
+ * Tailwind 4, compiled into the bundle and added to the PCI's shadow root (index.tsx): its classes style only this PCI.
+ * The components use the utility classes directly; @source tells Tailwind where to find them.
+ */
 @import "tailwindcss";
 @source "./**/*.{html,js,ts,jsx,tsx}";
 @source "../*.xml";
-.pci-container {
-  @apply mx-auto flex w-full max-w-xl flex-col items-center gap-5 rounded-2xl border border-slate-200 bg-white p-6 shadow-lg;
-}
-.title {
-  @apply text-center text-2xl font-semibold tracking-tight text-slate-800;
-}
-.body {
-  @apply flex w-full justify-center;
-}
-.body-image {
-  @apply rounded-xl border border-slate-200 bg-slate-50 p-2;
-}
-.interaction {
-  @apply w-full rounded-xl border border-slate-200 bg-slate-50 p-4;
-}
-.prompt {
-  @apply mb-2 block text-sm font-medium text-slate-700;
-}
-.answer-row {
-  @apply flex items-center gap-2;
-}
-.answer-input {
-  @apply w-28 rounded-lg border border-slate-300 bg-white px-3 py-2 text-lg font-medium text-slate-900 shadow-sm outline-none transition focus:border-amber-500 focus:ring-2 focus:ring-amber-200;
-}
-.answer-suffix {
-  @apply text-sm font-semibold uppercase tracking-wide text-slate-500;
-}

package/preset/typescript/src/index.ts

@@ -1,191 +1,187 @@
+/*
+ * A Portable Custom Interaction (PCI) in plain TypeScript.
+ *
+ * The delivery engine (the player) loads this bundle, which registers a factory with qtiCustomInteractionContext.
+ * For every interaction in an item the engine calls factory.getInstance(dom, config, state); the instance renders
+ * into `dom` and reports its answer through getResponse().
+ *
+ * The demo: "what percentage of the circle is coloured?". The circle is drawn from the settings in src/config.json
+ * (pie.ts); the answer is a whole number, reported as { base: { integer: 30 } } (see config.tspci.response in
+ * package.json and AUTHORING.md).
+ */
 import {
   ConfigProperties,
   IMSpci,
   IMSpciFactory,
+  PciProperties,
   QtiInteractionChangedDetail,
   QtiVariableJSON,
 } from "@citolab/tspci";
-import * as ctx from "qtiCustomInteractionContext";
-import configProps from "./config.json";
-import Interaction from "./interaction"; // import and bundle this interaction file
-
-import style from "./styles.css"; // import and bundle this style file ( you can use tailwind and nested css )
-import procenten from "./assets/procenten.png"; // image types are bundled inside the js
-// Configuration
-type PropTypes = typeof configProps;
-
-type PciState = {
-  value: string;
-  touched: boolean;
-  customValidity?: string;
-};
+import * as ctx from "qtiCustomInteractionContext"; // provided by the delivery engine at runtime
+import configProps from "./config.json"; // the settings; the build passes only their defaults (AUTHORING.md)
+import style from "./styles.css"; // bundled as a string, added to the shadow root below
+import { escapeHtml, pieSvg } from "./pie";
+// Images are bundled too: `import logo from "./assets/logo.png"` gives a data URL for <img src>.
+
+// Like every data- attribute, each setting arrives as a string.
+type PropTypes = PciProperties<typeof configProps>;
+
+/** What getState() saves and the constructor restores: the text in the input, also when it is not a number yet. */
+type PciState = { value: string };
+
+/** The response for the text in the input: a whole number, or undefined while there is no answer. */
+function toResponse(value: string): QtiVariableJSON | undefined {
+  const trimmed = value.trim();
+  if (trimmed === "") return undefined; // nothing answered, nothing reported
+  const n = Number(trimmed);
+  // One answer, one response: "30", "030" and "30.0" all report 30.
+  return Number.isFinite(n) ? { base: { integer: Math.round(n) } } : undefined;
+}
+
+/** The input text for a response (setResponse, boundTo) or a correct response (status "solution"). */
+function fromResponse(value: unknown): string {
+  if (Array.isArray(value)) return fromResponse(value[0]);
+  if (value && typeof value === "object") {
+    const base = (value as QtiVariableJSON).base;
+    return fromResponse(base?.integer ?? base?.float ?? base?.string);
+  }
+  return value === undefined || value === null ? "" : String(value);
+}
 
 class PciInstance implements IMSpci<PropTypes> {
   typeIdentifier = "###___PCI_NAME___###";
   private config: ConfigProperties<PropTypes>;
   private dom: HTMLElement;
   private shadowdom: ShadowRoot;
-  private state: PciState;
-  private onChange: (e: Event) => void;
+  private state: PciState = { value: "" };
+  private customValidity = "";
 
   constructor(dom: HTMLElement, config: ConfigProperties<PropTypes>, stateString?: string) {
     if (!dom) throw new Error("No DOM Element provided");
-    config.properties = { ...configProps, ...config.properties };
+    // The item's data- attributes override the defaults from config.json.
+    config.properties = { ...(configProps as unknown as PropTypes), ...config.properties };
     this.dom = dom;
     this.config = config;
+    // A closed shadow root keeps the item's CSS out and ours in.
     this.shadowdom = dom.attachShadow({ mode: "closed" });
 
-    this.state = { value: "", touched: false };
+    // 1. The state from a previous session (whatever getState() returned).
     if (stateString) {
       try {
         const parsed = JSON.parse(stateString) as Partial<PciState>;
-        this.state = {
-          value: typeof parsed.value === "string" ? parsed.value : "",
-          touched: parsed.touched === true,
-          customValidity: typeof parsed.customValidity === "string" ? parsed.customValidity : undefined,
-        };
+        this.state = { value: typeof parsed?.value === "string" ? parsed.value : "" };
       } catch {
-        this.state = { value: typeof stateString === "string" ? stateString : "", touched: false };
+        // not ours: start empty
       }
     }
+    // 2. A response the engine binds to the interaction (boundTo) wins over the state.
+    const boundTo = config.boundTo ?? {};
+    const bound = boundTo[config.responseIdentifier] ?? (Object.keys(boundTo).length === 1 ? Object.values(boundTo)[0] : undefined);
+    if (bound) this.state = { value: fromResponse(bound) };
 
-    const boundResponse =
-      this.config.boundTo?.[this.config.responseIdentifier] ??
-      (this.config.boundTo && Object.keys(this.config.boundTo).length === 1
-        ? this.config.boundTo[Object.keys(this.config.boundTo)[0]]
-        : undefined);
-    if (boundResponse && (boundResponse.base || boundResponse.list || boundResponse.record)) {
-      this.setResponse?.(boundResponse);
-    }
+    this.render();
+    // 3. Status "solution": show the correct response of the item instead (AUTHORING.md, "Correct answers").
+    if (config.status === "solution") this.showCorrectResponse();
 
-    this.onChange = (e: Event) => {
-      const target = e.target as HTMLInputElement | null;
-      if (!target) return;
-      const nextValue = target.value ?? "";
-      if (nextValue === this.state.value && this.state.touched) return;
-      this.state = { ...this.state, value: nextValue, touched: true };
-      this.dispatchInteractionChanged();
-    };
+    config.onready?.(this, this.getState());
+  }
 
-    this.render();
+  /** Read-only when the candidate can no longer answer. */
+  private get readOnly() {
+    return ["review", "solution", "closed"].includes(this.config.status ?? "interacting");
+  }
 
-    if (this.config.onready) {
-      this.config.onready(this, this.getState());
-    }
+  private get input() {
+    return this.shadowdom.querySelector<HTMLInputElement>("input");
   }
 
-  private getInputEl(): HTMLInputElement | null {
-    return this.shadowdom.querySelector("input[type='number']");
+  private render() {
+    const p = this.config.properties;
+    // <label for> ties the question to the input, so a screen reader reads it and a click on it focuses the input.
+    this.shadowdom.innerHTML = `
+      <style>${style}</style>
+      <div class="pci">
+        <h2 class="title">${escapeHtml(p.title)}</h2>
+        ${pieSvg(p)}
+        <label class="question" for="answer">${escapeHtml(p.question)}</label>
+        <div class="answer">
+          <input id="answer" type="number" inputmode="numeric" min="0" max="100" step="1" autocomplete="off"
+            value="${escapeHtml(this.state.value)}" ${this.readOnly ? "disabled" : ""} />
+          <span class="unit">%</span>
+        </div>
+      </div>`;
+
+    const input = this.input;
+    input.setCustomValidity(this.customValidity);
+    this.markValidity();
+    input.addEventListener("input", this.onInput);
   }
 
-  private dispatchInteractionChanged() {
+  private onInput = () => {
+    this.state = { value: this.input.value };
+    this.markValidity();
+    // Tell the engine the response changed; composed lets the event cross the shadow root.
     const detail: QtiInteractionChangedDetail = {
       interaction: this,
       responseIdentifier: this.config.responseIdentifier,
-      valid: this.checkValidity?.() ?? true,
+      valid: this.checkValidity(),
       value: this.getResponse(),
     };
-    const event = new CustomEvent("qti-interaction-changed", {
-      bubbles: true,
-      composed: true,
-      cancelable: true,
-      detail,
-    });
-    this.dom.dispatchEvent(event);
-  }
+    this.dom.dispatchEvent(new CustomEvent("qti-interaction-changed", { bubbles: true, composed: true, detail }));
+  };
 
-  private render() {
-    this.shadowdom.innerHTML = `<div class="pci-container">
-      <h1>${this.config.properties.title}</h1>
-      <div class="body">
-        <img width="${+this.config.properties.width}" height="${+this.config
-      .properties.height}" src="${procenten}" />
-      </div>
-      <div class="interaction">
-        <label>${this.config.properties.prompt}</label>
-        <input type="number" value="${this.state.value}" min="0" max="100">%
-      </div>
-    </div>`;
-
-    const css = document.createElement("style");
-    css.innerHTML = style;
-    this.shadowdom.appendChild(css);
-
-    const input = this.getInputEl();
-    if (input) {
-      if (this.state.customValidity) input.setCustomValidity(this.state.customValidity);
-      input.addEventListener("input", this.onChange);
-      input.addEventListener("change", this.onChange);
-    }
+  /** aria-invalid tells assistive technology, and styles.css shows it with a red outline. */
+  private markValidity() {
+    const input = this.input;
+    input.setAttribute("aria-invalid", String(input.value !== "" && !input.checkValidity()));
   }
 
-  setResponse = (response: QtiVariableJSON) => {
-    const next =
-      typeof response?.base?.integer === "number"
-        ? String(response.base.integer)
-        : typeof response?.base?.string === "string"
-          ? response.base.string
-          : "";
-    this.state = { ...this.state, value: next, touched: true };
-    const input = this.getInputEl();
-    if (input) input.value = next;
+  /** Show the correct response the item declares (status "solution"); without one, keep what is there. */
+  showCorrectResponse = () => {
+    const correct = this.config.responseDeclaration?.correctResponse?.value;
+    if (correct === undefined) return;
+    this.state = { value: fromResponse(correct) };
+    this.render();
   };
 
-  getResponse = () => {
-    if (!this.state.touched) return undefined;
-    const trimmed = (this.state.value ?? "").toString().trim();
-    if (!trimmed) return undefined;
-    const asNumber = Number(trimmed);
-    if (!Number.isFinite(asNumber)) return undefined;
-    return { base: { integer: Math.trunc(asNumber) } } as QtiVariableJSON;
-  };
+  // ---- the IMS PCI API ----
+
+  getResponse = () => toResponse(this.state.value);
 
   getState = () => JSON.stringify(this.state);
 
-  checkValidity = () => {
-    const input = this.getInputEl();
-    if (!input) return undefined;
-    return input.checkValidity();
+  setResponse = (response: QtiVariableJSON) => {
+    this.state = { value: fromResponse(response) };
+    this.render();
   };
 
-  reportValidity = () => {
-    const input = this.getInputEl();
-    if (!input) return undefined;
-    return input.reportValidity();
-  };
+  checkValidity = () => this.input?.checkValidity() ?? true;
+
+  reportValidity = () => this.input?.reportValidity() ?? true;
 
   setCustomValidity = (message: string) => {
-    this.state = { ...this.state, customValidity: message };
-    const input = this.getInputEl();
-    if (input) input.setCustomValidity(message);
+    this.customValidity = message ?? "";
+    this.input?.setCustomValidity(this.customValidity);
   };
 
-  getCustomValidity = () => this.state.customValidity ?? "";
+  getCustomValidity = () => this.customValidity;
 
+  /** The engine is done with this instance: release what you hold (listeners on window, timers, ...). */
   oncompleted = () => {
-    const input = this.getInputEl();
-    if (input) {
-      input.removeEventListener("input", this.onChange);
-      input.removeEventListener("change", this.onChange);
-    }
+    this.input?.removeEventListener("input", this.onInput);
   };
 }
 
 const factory: IMSpciFactory<PropTypes> = {
-  typeIdentifier: "###___PCI_NAME___###",
+  typeIdentifier: "###___PCI_NAME___###", // the same as config.tspci.typeIdentifier in package.json
   getInstance: (dom, config, state) => new PciInstance(dom, config, state),
 };
 
-const engineContext =
-  ctx && typeof (ctx as unknown as { register?: unknown }).register === "function"
-    ? (ctx as unknown as { register: (f: IMSpciFactory<PropTypes>) => void })
-    : typeof window !== "undefined" && (window as unknown as { qtiCustomInteractionContext?: unknown }).qtiCustomInteractionContext
-      ? ((window as unknown as { qtiCustomInteractionContext: { register: (f: IMSpciFactory<PropTypes>) => void } })
-          .qtiCustomInteractionContext as { register: (f: IMSpciFactory<PropTypes>) => void })
-      : undefined;
-
-if (engineContext) {
-  engineContext.register(factory);
-}
+// Register with the engine: as an AMD module (qtiCustomInteractionContext), or through the global some engines set.
+type Context = { register: (factory: IMSpciFactory<PropTypes>) => void };
+const engineContext = [ctx as unknown as Context, (globalThis as { qtiCustomInteractionContext?: Context }).qtiCustomInteractionContext].find(
+  (c) => typeof c?.register === "function"
+);
+engineContext?.register(factory);
 
 export default factory;

package/preset/typescript/src/pie.ts

@@ -0,0 +1,51 @@
+import type { PciProperties } from "@citolab/tspci";
+import configProps from "./config.json";
+
+type PropTypes = PciProperties<typeof configProps>;
+
+/** Settings arrive as strings (they are data- attributes) and an author may type anything: parse and clamp them. */
+const toInt = (value: string, fallback: number, min: number, max: number) => {
+  const n = Number.parseInt(value, 10);
+  return Number.isNaN(n) ? fallback : Math.min(max, Math.max(min, n));
+};
+
+/** The pie the settings describe; the limits match the min/max in config.json. */
+export function pieSettings(p: PropTypes) {
+  const segments = toInt(p.segments, 10, 2, 24);
+  return {
+    segments,
+    colored: toInt(p.colored, 0, 0, segments),
+    size: toInt(p.size, 200, 100, 400),
+    color: p.color || "#3b82f6",
+  };
+}
+
+/** An SVG circle of `segments` equal slices, the first `colored` ones filled, clockwise from the top. */
+export function pieSvg(p: PropTypes): string {
+  const { segments, colored, size, color } = pieSettings(p);
+  const c = size / 2; // centre
+  const r = c - 4; // leave room for the outline
+  const point = (i: number) => {
+    const angle = -Math.PI / 2 + (2 * Math.PI * i) / segments;
+    return `${(c + r * Math.cos(angle)).toFixed(2)} ${(c + r * Math.sin(angle)).toFixed(2)}`;
+  };
+  const slices = Array.from(
+    { length: segments },
+    (_, i) =>
+      `<path class="slice" d="M ${c} ${c} L ${point(i)} A ${r} ${r} 0 0 1 ${point(i + 1)} Z"${
+        i < colored ? ` fill="${escapeHtml(color)}"` : ""
+      }/>`
+  ).join("");
+  // role="img" + aria-label: a screen reader reads one description instead of a list of paths.
+  // Translate the label when your items are not in English.
+  return `<svg class="pie" viewBox="0 0 ${size} ${size}" width="${size}" height="${size}"
+    role="img" aria-label="A circle in ${segments} equal slices, ${colored} of them coloured">${slices}</svg>`;
+}
+
+/** Settings and answers end up in innerHTML: escape them, or an author's "<" breaks the markup. */
+export const escapeHtml = (value: unknown) =>
+  String(value ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");