@qti-components/portable-custom-interaction 1.0.1

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,CAAC;AAEpB,cAAc,mCAAmC,CAAC","sourcesContent":["import './register';\n\nexport * from './qti-portable-custom-interaction';\n"]}

package/dist/interface.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Shared status values for PCI lifecycle callbacks.
+ *
+ * Matches the status vocabulary used in IMS QTI 3 PCI documentation.
+ */
+export type PciInteractionStatus = 'interacting' | 'suspended' | 'closed' | 'solution' | 'review';
+/**
+ * Payload passed to `onready` once a PCI reports it is ready.
+ */
+export interface PciReadyPayload {
+    responseIdentifier: string;
+    status: PciInteractionStatus;
+}
+/**
+ * Payload that may be passed to `ondone` when PCI finishes candidate interaction.
+ */
+export interface PciDonePayload {
+    responseIdentifier: string;
+    status: PciInteractionStatus;
+    outcome?: unknown;
+}
+/**
+ * Configuration object shape exposed to a PCI instance.
+ *
+ * Notes for authors:
+ * - `properties` contains `data-*` attributes from the host element using dataset rules.
+ * - `templateVariables`, `contextVariables`, and `boundTo` follow QTI Appendix-C style JSON values.
+ * - `onready` must be called by the PCI once it is interactive.
+ * - `ondone` is optional and may be used for explicit completion workflows.
+ */
+export interface ConfigProperties<T> {
+    properties: T;
+    templateVariables: Record<string, unknown>;
+    contextVariables: Record<string, unknown>;
+    boundTo: unknown;
+    responseIdentifier: string;
+    onready: (payload: PciReadyPayload) => void;
+    ondone?: (payload: PciDonePayload) => void;
+    status?: PciInteractionStatus;
+}
+/**
+ * IMS-style PCI factory and instance contract.
+ *
+ * A PCI module registers an object with a `typeIdentifier` and a `getInstance(...)` factory method.
+ * The returned PCI instance should implement response/state read/write methods.
+ */
+export interface IMSpci<T> {
+    /**
+     * Stable PCI type key, expected to match `custom-interaction-type-identifier`.
+     */
+    typeIdentifier: string;
+    /** @access public
+     *  @method getInstance Create a new instance of this portable custom interaction
+     *  Will be called by the qtiCustomInteractionContext
+     *  @param {DOM Element} dom - the DOM Element this PCI is being added to
+     *  @param {Object} configuration - the configuration to apply to this PCI
+     *  @param {String} state - a previous saved state to apply to this instance.
+     *  This must have been obtained from a prior call to getState on an
+     *  instance of this type (same typeIdentifier)
+     */
+    getInstance: (dom: HTMLElement, configuration: Configuration<T>, state: string) => void;
+    /** @access public
+     * @method getResponse
+     * @return {Object} - the value to assign to the bound QTI response variable
+     */
+    getResponse: () => QtiVariableJSON | undefined;
+    /** @access public
+     * @method setResponse
+     * @param {Object} value - the value to assign to the bound QTI response variable
+     * NOTE: This is not an official QTI method, so no guarantee it is implemented
+     * in all PCIs.
+     */
+    setResponse: (value: QtiVariableJSON) => void;
+    /** @access public
+     * @method getState
+     * @return {String} The current state of this PCI. May be passed to
+     * getInstance to later restore this PCI instance.
+     * FIXME: host runtime can round-trip object states via prefixed JSON strings;
+     * this type remains `string` for IMS compatibility.
+     */
+    getState: () => string;
+    /** @access public
+     * @method setState
+     * @param {String} value - a state previously obtained from getState
+     * to restore this PCI instance to a prior state.
+     * FIXME: runtime may deserialize prefixed JSON state before applying it.
+     */
+    setState(value: string): unknown;
+    /**
+     * Optional teardown callback. If present, host may call before unload/cleanup.
+     */
+    oncompleted?: () => void;
+    /**
+     * Non-standard optional destroy hook; included for compatibility with legacy engines.
+     */
+    destroy?: () => void;
+}
+/**
+ * Bridge callback signature used by this codebase for PCI registration.
+ *
+ * IMPORTANT:
+ * - This type is intentionally minimal for existing call sites.
+ * - Runtime initialization payload in `qti-portable-custom-interaction.ts` contains
+ *   additional fields (`boundTo`, `templateVariables`, `contextVariables`, etc.).
+ * FIXME: align this type with runtime payload to remove ambiguity in generated docs.
+ */
+export declare type Configuration<T> = {
+    onready: (pci: IMSpci<ConfigProperties<T>>, state?: string) => void;
+    properties: T;
+};
+/**
+ * QTI base-type `file` representation.
+ */
+export type QtiFileData = {
+    data: string;
+    mime: string;
+    name?: string;
+};
+export type QtiBaseBoolean = boolean;
+export type QtiBaseInteger = number;
+export type QtiBaseFloat = number;
+export type QtiBaseString = string;
+export type QtiBasePoint = [number, number];
+export type QtiBasePair = [string, string];
+export type QtiBaseDirectedPair = [string, string];
+export type QtiBaseDuration = string;
+export type QtiBaseFile = QtiFileData;
+export type QtiBaseUri = string;
+export type QtiBaseIntOrIdentifier = number | string;
+export type QtiBaseIdentifier = string;
+/**
+ * Convenience union for primitive response values used by this implementation.
+ */
+export type ResponseType = boolean | number | string | QtiBasePair | QtiBasePoint | QtiFileData | Array<boolean | number | string | QtiBasePair | QtiBasePoint | QtiFileData>;
+/**
+ * A QTI record entry for `record` cardinality values.
+ */
+export type QtiRecordItem = {
+    name: string;
+    base?: QtiBaseTypeJSON | null;
+    list?: QtiListTypeJSON | null;
+};
+export type ResponseVariableType = QtiVariableJSON;
+/**
+ * QTI Appendix-C style JSON representation for base cardinality.
+ */
+export type QtiBaseTypeJSON = {
+    boolean?: QtiBaseBoolean;
+    integer?: QtiBaseInteger;
+    float?: QtiBaseFloat;
+    string?: QtiBaseString;
+    point?: QtiBasePoint;
+    pair?: QtiBasePair;
+    directedPair?: QtiBaseDirectedPair;
+    duration?: QtiBaseDuration;
+    file?: QtiBaseFile;
+    uri?: QtiBaseUri;
+    intOrIdentifier?: QtiBaseIntOrIdentifier;
+    identifier?: QtiBaseIdentifier;
+} | null;
+/**
+ * QTI Appendix-C style JSON representation for list cardinality.
+ */
+export type QtiListTypeJSON = {
+    boolean?: QtiBaseBoolean[];
+    integer?: QtiBaseInteger[];
+    float?: QtiBaseFloat[];
+    string?: QtiBaseString[];
+    point?: QtiBasePoint[];
+    pair?: QtiBasePair[];
+    directedPair?: QtiBaseDirectedPair[];
+    duration?: QtiBaseDuration[];
+    file?: QtiBaseFile[];
+    uri?: QtiBaseUri[];
+    intOrIdentifier?: QtiBaseIntOrIdentifier[];
+    identifier?: QtiBaseIdentifier[];
+} | null;
+/**
+ * Complete QTI variable JSON envelope used by PCI bridge messaging.
+ */
+export declare type QtiVariableJSON = {
+    base?: QtiBaseTypeJSON;
+    list?: QtiListTypeJSON;
+    record?: QtiRecordItem[] | null;
+};
+/**
+ * RequireJS module resolution config accepted by helper utilities and stories.
+ */
+export interface ModuleResolutionConfig {
+    waitSeconds?: number;
+    context?: string;
+    catchError?: boolean;
+    paths: {
+        [key: string]: string | string[];
+    };
+    shim?: {
+        [key: string]: {
+            deps?: string[];
+            exports?: string;
+        };
+    };
+}

package/dist/interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=interface.js.map

package/dist/interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../src/interface.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Shared status values for PCI lifecycle callbacks.\n *\n * Matches the status vocabulary used in IMS QTI 3 PCI documentation.\n */\nexport type PciInteractionStatus = 'interacting' | 'suspended' | 'closed' | 'solution' | 'review';\n\n/**\n * Payload passed to `onready` once a PCI reports it is ready.\n */\nexport interface PciReadyPayload {\n  responseIdentifier: string; // The response identifier of the PCI\n  status: PciInteractionStatus; // Current status\n}\n\n/**\n * Payload that may be passed to `ondone` when PCI finishes candidate interaction.\n */\nexport interface PciDonePayload {\n  responseIdentifier: string; // The response identifier of the PCI\n  status: PciInteractionStatus; // The final status after completion\n  outcome?: unknown; // Optional outcome data (e.g., score, correctness)\n}\n\n/**\n * Configuration object shape exposed to a PCI instance.\n *\n * Notes for authors:\n * - `properties` contains `data-*` attributes from the host element using dataset rules.\n * - `templateVariables`, `contextVariables`, and `boundTo` follow QTI Appendix-C style JSON values.\n * - `onready` must be called by the PCI once it is interactive.\n * - `ondone` is optional and may be used for explicit completion workflows.\n */\nexport interface ConfigProperties<T> {\n  properties: T; // Follows dataset conversion rules (camelCased keys)\n  templateVariables: Record<string, unknown>; // Follows structure in Appendix C\n  contextVariables: Record<string, unknown>; // Follows structure in Appendix C\n  boundTo: unknown; // Follows structure in Appendix C\n  responseIdentifier: string; // Unique within interaction scope\n\n  onready: (payload: PciReadyPayload) => void; // Callback for when PCI is fully constructed and ready\n  ondone?: (payload: PciDonePayload) => void; // Optional callback when candidate finishes interaction\n\n  status?: PciInteractionStatus; // Optional, defaults to \"interacting\"\n}\n\n/**\n * IMS-style PCI factory and instance contract.\n *\n * A PCI module registers an object with a `typeIdentifier` and a `getInstance(...)` factory method.\n * The returned PCI instance should implement response/state read/write methods.\n */\nexport interface IMSpci<T> {\n  /**\n   * Stable PCI type key, expected to match `custom-interaction-type-identifier`.\n   */\n  typeIdentifier: string;\n\n  /** @access public\n   *  @method getInstance Create a new instance of this portable custom interaction\n   *  Will be called by the qtiCustomInteractionContext\n   *  @param {DOM Element} dom - the DOM Element this PCI is being added to\n   *  @param {Object} configuration - the configuration to apply to this PCI\n   *  @param {String} state - a previous saved state to apply to this instance.\n   *  This must have been obtained from a prior call to getState on an\n   *  instance of this type (same typeIdentifier)\n   */\n  getInstance: (dom: HTMLElement, configuration: Configuration<T>, state: string) => void;\n\n  /** @access public\n   * @method getResponse\n   * @return {Object} - the value to assign to the bound QTI response variable\n   */\n  getResponse: () => QtiVariableJSON | undefined;\n\n  /** @access public\n   * @method setResponse\n   * @param {Object} value - the value to assign to the bound QTI response variable\n   * NOTE: This is not an official QTI method, so no guarantee it is implemented\n   * in all PCIs.\n   */\n  setResponse: (value: QtiVariableJSON) => void;\n\n  /** @access public\n   * @method getState\n   * @return {String} The current state of this PCI. May be passed to\n   * getInstance to later restore this PCI instance.\n   * FIXME: host runtime can round-trip object states via prefixed JSON strings;\n   * this type remains `string` for IMS compatibility.\n   */\n  getState: () => string;\n\n  /** @access public\n   * @method setState\n   * @param {String} value - a state previously obtained from getState\n   * to restore this PCI instance to a prior state.\n   * FIXME: runtime may deserialize prefixed JSON state before applying it.\n   */\n  setState(value: string): unknown;\n\n  /**\n   * Optional teardown callback. If present, host may call before unload/cleanup.\n   */\n  oncompleted?: () => void;\n\n  /**\n   * Non-standard optional destroy hook; included for compatibility with legacy engines.\n   */\n  destroy?: () => void; // Not used in IMS and not in TAO implementation, so not used here (optional)\n}\n\n/**\n * Bridge callback signature used by this codebase for PCI registration.\n *\n * IMPORTANT:\n * - This type is intentionally minimal for existing call sites.\n * - Runtime initialization payload in `qti-portable-custom-interaction.ts` contains\n *   additional fields (`boundTo`, `templateVariables`, `contextVariables`, etc.).\n * FIXME: align this type with runtime payload to remove ambiguity in generated docs.\n */\nexport declare type Configuration<T> = {\n  onready: (pci: IMSpci<ConfigProperties<T>>, state?: string) => void;\n  properties: T;\n  // PK: following this: https://www.imsglobal.org/spec/qti/v3p0/impl#h.1mc9puik2ft6\n  // All below are not used in the IMS Reference implementation, keeping for ref\n  /*    \n  ondone: (pci: IMSPci<T>,response:any,state:string, status?: \"interacting\" | \"closed\" | \"solution\" | \"review\" ) => void;\n  status: string;\n  templateVariables: any;  \n  boundTo: any;\n  contextVariables\n  responseIdentifier\n  */\n};\n\n/**\n * QTI base-type `file` representation.\n */\nexport type QtiFileData = {\n  data: string;\n  mime: string;\n  name?: string;\n};\n\nexport type QtiBaseBoolean = boolean;\nexport type QtiBaseInteger = number;\nexport type QtiBaseFloat = number;\nexport type QtiBaseString = string;\nexport type QtiBasePoint = [number, number];\nexport type QtiBasePair = [string, string];\nexport type QtiBaseDirectedPair = [string, string];\nexport type QtiBaseDuration = string; // ISO 8601 duration format\nexport type QtiBaseFile = QtiFileData;\nexport type QtiBaseUri = string;\nexport type QtiBaseIntOrIdentifier = number | string;\nexport type QtiBaseIdentifier = string;\n\n/**\n * Convenience union for primitive response values used by this implementation.\n */\nexport type ResponseType =\n  | boolean\n  | number\n  | string\n  | QtiBasePair\n  | QtiBasePoint\n  | QtiFileData\n  | Array<boolean | number | string | QtiBasePair | QtiBasePoint | QtiFileData>;\n\n/**\n * A QTI record entry for `record` cardinality values.\n */\nexport type QtiRecordItem = {\n  name: string;\n  base?: QtiBaseTypeJSON | null;\n  list?: QtiListTypeJSON | null;\n};\nexport type ResponseVariableType = QtiVariableJSON;\n\n/**\n * QTI Appendix-C style JSON representation for base cardinality.\n */\nexport type QtiBaseTypeJSON = {\n  boolean?: QtiBaseBoolean;\n  integer?: QtiBaseInteger;\n  float?: QtiBaseFloat;\n  string?: QtiBaseString;\n  point?: QtiBasePoint;\n  pair?: QtiBasePair;\n  directedPair?: QtiBaseDirectedPair;\n  duration?: QtiBaseDuration;\n  file?: QtiBaseFile;\n  uri?: QtiBaseUri;\n  intOrIdentifier?: QtiBaseIntOrIdentifier;\n  identifier?: QtiBaseIdentifier;\n} | null;\n\n/**\n * QTI Appendix-C style JSON representation for list cardinality.\n */\nexport type QtiListTypeJSON = {\n  boolean?: QtiBaseBoolean[];\n  integer?: QtiBaseInteger[];\n  float?: QtiBaseFloat[];\n  string?: QtiBaseString[];\n  point?: QtiBasePoint[];\n  pair?: QtiBasePair[];\n  directedPair?: QtiBaseDirectedPair[];\n  duration?: QtiBaseDuration[];\n  file?: QtiBaseFile[];\n  uri?: QtiBaseUri[];\n  intOrIdentifier?: QtiBaseIntOrIdentifier[];\n  identifier?: QtiBaseIdentifier[];\n} | null;\n\n/**\n * Complete QTI variable JSON envelope used by PCI bridge messaging.\n */\nexport declare type QtiVariableJSON = {\n  base?: QtiBaseTypeJSON;\n  list?: QtiListTypeJSON;\n  record?: QtiRecordItem[] | null;\n};\n\n/**\n * RequireJS module resolution config accepted by helper utilities and stories.\n */\nexport interface ModuleResolutionConfig {\n  waitSeconds?: number;\n  context?: string;\n  catchError?: boolean;\n  paths: {\n    [key: string]: string | string[];\n  };\n  shim?: {\n    [key: string]: {\n      deps?: string[]; // Array of dependencies\n      exports?: string; // The global variable to use as the module's value\n    };\n  };\n}\n"]}

package/dist/qti-portable-custom-interaction.d.ts

@@ -0,0 +1,115 @@
+import { Interaction } from '@qti-components/base';
+import type { CSSResultGroup } from 'lit';
+import type { BaseType, Cardinality, ItemContext, QtiContext } from '@qti-components/base';
+import type { QtiVariableJSON, ResponseVariableType } from './interface';
+export declare class QtiPortableCustomInteraction extends Interaction {
+    #private;
+    protected _iframeLoaded: boolean;
+    protected _pendingMessages: Array<{
+        method: string;
+        params: any;
+    }>;
+    protected iframe: HTMLIFrameElement;
+    protected _iframeMessageOrigin: string | null;
+    private _iframeObjectUrl;
+    static styles: CSSResultGroup;
+    module: string;
+    customInteractionTypeIdentifier: string;
+    requirePathsJson: string;
+    requireShimJson: string;
+    requireJsUrl: string;
+    baseUrl: string;
+    useDefaultPaths: boolean;
+    private _errorMessage;
+    protected context?: ItemContext;
+    protected qtiContext?: QtiContext;
+    response: string | string[] | null;
+    /**
+     * Get direct child elements by tag name
+     */
+    private getDirectChildrenByTag;
+    /**
+     * Coerce a scalar value to the expected base-type when possible
+     */
+    private coerceBaseValue;
+    /**
+     * Normalize an input into a list form
+     */
+    private normalizeListValue;
+    /**
+     * Convert a variable value to QtiVariableJSON
+     */
+    private variableToQtiVariableJSON;
+    /**
+     * Convert a record object into QtiVariableJSON
+     */
+    private recordToQtiVariableJSON;
+    /**
+     * Build a record entry from an arbitrary value
+     */
+    private recordEntryFromValue;
+    /**
+     * Extract default QTI_CONTEXT values from qti-context-declaration elements
+     */
+    private getQtiContextDefaultsFromItem;
+    /**
+     * Build a QTI_CONTEXT record for PCI consumption
+     */
+    private getQtiContextRecord;
+    /**
+     * Collect template variables referenced by qti-template-variable children
+     */
+    private getTemplateVariables;
+    /**
+     * Collect context variables referenced by qti-context-variable children
+     */
+    private getContextVariables;
+    /**
+     * Converts response variables to QtiVariableJSON
+     */
+    protected responseVariablesToQtiVariableJSON(input: string | string[], cardinality: Cardinality, baseType: BaseType): QtiVariableJSON;
+    validate(): boolean;
+    set value(v: string | null);
+    get value(): string | null;
+    set boundTo(newValue: Record<string, ResponseVariableType>);
+    get boundTo(): Record<string, QtiVariableJSON>;
+    disconnectedCallback(): void;
+    /**
+     * IFRAME MODE: Send message to iframe
+     */
+    protected sendMessageToIframe(method: string, params: any): void;
+    /**
+     * IFRAME MODE: Handle iframe messages
+     */
+    protected handleIframeMessage: (event: MessageEvent) => void;
+    /**
+     * IFRAME MODE: Create iframe element
+     */
+    protected createIframe(): void;
+    connectedCallback(): void;
+    /**
+     * IFRAME MODE: Generate iframe HTML content
+     */
+    protected generateIframeContent(): string;
+    /**
+     * Toggle the display of the correct response
+     * @param responseVariable The response variable containing the correct response
+     * @param show Whether to show or hide the correct response
+     */
+    toggleInternalCorrectResponse(show: boolean): void;
+    /**
+     * Method to disable the PCI for review mode
+     * This can be used when showing the correct response
+     */
+    disable(): void;
+    /**
+     * Method to enable the PCI for interactive mode
+     */
+    enable(): void;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'qti-portable-custom-interaction': QtiPortableCustomInteraction;
+    }
+}