@citolab/qti-components 8.0.0 → 8.0.1

package/dist/qti-rule-base.d-ajOnfGXY.d.ts

@@ -0,0 +1,16 @@
+import { LitElement } from 'lit';
+
+/**
+ * Interface for any object that can process QTI rules
+ */
+interface QtiRuleBase {
+    process(): any;
+}
+/**
+ * Abstract base class for QTI rule DOM elements
+ */
+declare abstract class QtiRuleElement extends LitElement implements QtiRuleBase {
+    abstract process(): any;
+}
+
+export { type QtiRuleBase as Q, QtiRuleElement as a };

package/dist/qti-transform-test.d-BL7GGFJj.d.ts

@@ -0,0 +1,70 @@
+interface ModuleResolutionConfig {
+    waitSeconds?: number;
+    context?: string;
+    catchError?: boolean;
+    urlArgs?: string;
+    paths: {
+        [key: string]: string | string[];
+    };
+    shim?: {
+        [key: string]: {
+            deps?: string[];
+            exports?: string;
+        };
+    };
+}
+
+type transformItemApi = {
+    load: (uri: string, signal?: AbortSignal) => Promise<transformItemApi>;
+    parse: (xmlString: string) => transformItemApi;
+    path: (location: string) => transformItemApi;
+    fn: (fn: (xmlFragment: XMLDocument) => void) => transformItemApi;
+    pciHooks: (uri: string) => transformItemApi;
+    configurePci: (baseUrl: string, getModuleResolutionConfig: (baseUrl: string, fileUrl: string) => Promise<ModuleResolutionConfig>, selector?: string) => Promise<transformItemApi>;
+    extendElementName: (elementName: string, extend: string) => transformItemApi;
+    extendElementsWithClass: (param?: string) => transformItemApi;
+    customInteraction: (baseRef: string, baseItem: string) => transformItemApi;
+    convertCDATAtoComment: () => transformItemApi;
+    shuffleInteractions: (seed?: string | number | null) => transformItemApi;
+    stripStyleSheets: () => transformItemApi;
+    html: () => string;
+    xml: () => string;
+    htmlDoc: (registry?: CustomElementRegistry) => DocumentFragment;
+    xmlDoc: () => XMLDocument;
+};
+declare const qtiTransformItem: () => transformItemApi;
+
+/**
+ * Returns an object with methods to load, parse and transform QTI tests.
+ * @returns An object with methods to load, parse and transform QTI tests.
+ * @example
+ * const qtiTransformer = qtiTransformTest();
+ * await qtiTransformer.load('https://example.com/test.xml');
+ * const items = qtiTransformer.items();
+ * const html = qtiTransformer.html();
+ * const xml = qtiTransformer.xml();
+ */
+type transformTestApi = {
+    load: (uri: string, signal?: AbortSignal) => Promise<transformTestApi>;
+    parse: (xmlString: string) => transformTestApi;
+    path: (location: string) => transformTestApi;
+    fn: (fn: (xmlFragment: XMLDocument) => void) => transformTestApi;
+    /**
+     * Deterministically shuffle the children of every section that carries a
+     * <qti-ordering shuffle="true">, honoring fixed items and nested
+     * keep-together / visible rules. The same seed reproduces the same order.
+     */
+    shuffleOrdering: (seed?: string | number | null) => transformTestApi;
+    items: () => {
+        identifier: string;
+        href: string;
+        category: string;
+    }[];
+    html: () => string;
+    xml: () => string;
+    htmlDoc: (registry?: CustomElementRegistry) => DocumentFragment;
+    xmlDoc: () => XMLDocument;
+};
+declare const qtiTransformTest: () => transformTestApi;
+
+export { type ModuleResolutionConfig as M, qtiTransformTest as a, type transformTestApi as b, qtiTransformItem as q, type transformItemApi as t };

package/dist/qti.context.d-CejJMlfZ.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A validated deterministic shuffle seed.
+ *
+ * Branded so that only values verified through {@link isSeed} (or constructed via
+ * {@link asSeed}) can be assigned where a seed is expected. This prevents arbitrary
+ * strings from silently being used as a seed.
+ *
+ * A usable seed is a non-empty string of letters, digits and hyphens (e.g. a GUID
+ * "N" format like `8f14e45fceea167a5a36dedd4bea2543`, or a readable label like
+ * `delivery-2026-06-05`). Whitespace and other characters are rejected.
+ */
+type Seed = string & {
+    readonly __seedBrand: 'Seed';
+};
+/**
+ * Runtime type guard that narrows an unknown value to a {@link Seed}.
+ * Use this at boundaries (e.g. values coming from XML, a host application or a
+ * backend) before treating a string as a seed.
+ */
+declare const isSeed: (value: unknown) => value is Seed;
+/**
+ * Validates and brands a value as a {@link Seed}, returning `undefined` when the
+ * value is missing or not in a usable seed format.
+ */
+declare const asSeed: (value: unknown) => Seed | undefined;
+type QtiContextType = {
+    testIdentifier: string;
+    candidateIdentifier: string;
+    environmentIdentifier: string;
+    /**
+     * Optional deterministic seed for shuffling.
+     *
+     * When set, it is used to reproduce a stable shuffle order across reloads/restarts:
+     * - test ordering in `test-container` (`<qti-ordering shuffle="true">`),
+     * - seeded item interaction shuffling in `item-container` and during test navigation.
+     *
+     * Typically generated once per session by the host/backend and passed in via
+     * `QTI_CONTEXT`. When omitted, each item falls back to its own URI-derived seed.
+     */
+    seed?: Seed;
+    [key: string]: string | string[];
+};
+interface QtiContext {
+    QTI_CONTEXT: QtiContextType;
+}
+declare const qtiContext: {
+    __context__: Readonly<QtiContext>;
+};
+
+export { type QtiContext as Q, type Seed as S, type QtiContextType as a, asSeed as b, isSeed as i, qtiContext as q };

package/dist/response.d-_8y4kjGP.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Canonical `response="..."` / `correct-response="..."` attribute codec.
+ *
+ * Authors put a single string on an interaction element. This module is the
+ * single source of truth for how that string parses into the runtime's
+ * internal value AND how an editor serializes the internal value back to the
+ * attribute. Both `@qti-components/*` interactions and `@citolab/prose-qti`
+ * (the editor) import from here — no per-codebase parsers, no drift.
+ *
+ * The two attributes share the same grammar; the codec is agnostic about
+ * which of them is being parsed.
+ *
+ * ---
+ *
+ * Format reference (per interaction):
+ *
+ * | Interaction          | base-type     | cardinality          | attribute value           |
+ * |----------------------|---------------|----------------------|---------------------------|
+ * | choice               | identifier    | single / multiple    | "A"  /  "A,B,C"           |
+ * | inline-choice        | identifier    | single               | "Y"                       |
+ * | hottext              | identifier    | single / multiple    | "h1"  /  "h1,h2"          |
+ * | hotspot              | identifier    | single / multiple    | "spot1"  /  "spot1,spot2" |
+ * | order                | identifier    | ordered              | "a,b,c"  (order matters)  |
+ * | graphic-order        | identifier    | ordered              | "spot1,spot2,spot3"       |
+ * | match                | directedPair  | multiple             | "src1 tgt1,src2 tgt2"     |
+ * | associate            | directedPair  | multiple             | "A B,C D"                 |
+ * | gap-match            | directedPair  | multiple             | "gtext1 gap1,..."         |
+ * | graphic-associate    | directedPair  | multiple             | "spot1 spot2,..."         |
+ * | graphic-gap-match    | directedPair  | multiple             | "gimg1 spot1,..."         |
+ * | select-point         | point         | single / multiple    | "100 150"  /  "100 150,…" |
+ * | slider               | integer       | single               | "50"                      |
+ * | text-entry           | string        | single               | "paris"                   |
+ *
+ * Rules:
+ *  - Comma `,` separates VALUES (different identifiers / pairs / points).
+ *  - Space ` ` separates PARTS within one value (pair members or point coords).
+ *  - Each value is trimmed on parse.
+ *  - No escape mechanism. Identifiers that contain commas cannot round-trip.
+ */
+/** Canonical parsed value of a `response` / `correct-response` attribute. */
+type ResponseValue = string | string[] | null;
+/** Identifier literal — opaque QTI identifier (e.g. `"choice1"`). */
+type Identifier = string;
+/** Directed pair literal — `"sourceId targetId"`. Used by match / associate / gap-match. */
+type DirectedPair = `${string} ${string}`;
+/** Point literal — `"x y"` integer coordinates. Used by select-point / graphic-*. */
+type Point = `${number} ${number}`;
+/**
+ * Parse a raw `response` / `correct-response` attribute string into the
+ * canonical value.
+ *
+ *  - `null` / `undefined` / empty → `null`
+ *  - no comma                     → trimmed string
+ *  - one or more commas           → trimmed array (single-element collapses to a string)
+ */
+declare function parseResponseAttribute(raw: string | null | undefined): ResponseValue;
+/**
+ * Serialize a canonical value back to the attribute string. Returns `null` for
+ * empty inputs so a Lit `@property({ reflect: true })` drops the attribute.
+ */
+declare function serializeResponseAttribute(value: ResponseValue): string | null;
+/**
+ * Iterate over the comma-separated entries in a response value, regardless of
+ * whether the caller has the raw string, the parsed string, or a string[].
+ * Yields trimmed non-empty entries.
+ */
+declare function iterResponseValues(raw: ResponseValue): Generator<string>;
+/** Parse a directed-pair value into `{ source, target }`. Throws on malformed input. */
+declare function parsePair(value: string): {
+    source: string;
+    target: string;
+};
+/** Serialize a directed pair to canonical `"source target"` form. */
+declare function serializePair(source: string, target: string): DirectedPair;
+/** Parse a point value into `{ x, y }`. Throws on malformed input. */
+declare function parsePoint(value: string): {
+    x: number;
+    y: number;
+};
+/** Serialize a point to canonical `"x y"` form. */
+declare function serializePoint(x: number, y: number): Point;
+/**
+ * Ready-to-use Lit `converter` for `response` / `correct-response` attributes.
+ * Assign to the `converter` option:
+ *
+ *   @property({ attribute: 'response', converter: responseAttributeConverter({ emptyAs: [] }) })
+ *
+ * `emptyAs` picks the sentinel returned when the attribute is absent / blank.
+ * Three sentinels exist across the codebase — match the one your call site
+ * already uses. Future work may normalize to a single sentinel.
+ *
+ *   - '' (empty string)   — ChoicesMixin convention
+ *   - []                  — DragDropSlottedMixin / graphic-associate convention
+ *   - null                — base interaction / select-point convention
+ *
+ * On the serialize side, the `emptyAs` value roundtrips back to `null` so a
+ * `reflect: true` property drops the attribute rather than emitting `""`.
+ */
+declare function responseAttributeConverter<E extends '' | null | readonly unknown[]>(opts: {
+    emptyAs: E;
+}): {
+    fromAttribute: (value: string | null) => ResponseValue | E;
+    toAttribute: (value: ResponseValue | E) => string | null;
+};
+
+export { type DirectedPair as D, type Identifier as I, type Point as P, type ResponseValue as R, parsePoint as a, parseResponseAttribute as b, serializePoint as c, serializeResponseAttribute as d, iterResponseValues as i, parsePair as p, responseAttributeConverter as r, serializePair as s };