@superbuilders/incept-renderer 0.1.11 → 0.1.12

package/README.md

@@ -12,6 +12,7 @@ A secure, server-driven QTI 3.0 assessment renderer for React/Next.js applicatio
   - [Server Functions](#server-functions)
   - [Client Components](#client-components)
   - [Types](#types)
+- [Rendering Stimuli](#rendering-stimuli)
 - [Theming](#theming)
 - [Complete Examples](#complete-examples)
 - [Supported Interactions](#supported-interactions)
@@ -317,6 +318,29 @@ const result = await validateResponsesSecure(qtiXmlString, {
 }
 ```
 
+#### `parseAssessmentStimulusXml(xml: string)`
+
+Parses QTI Assessment Stimulus XML (reading materials, passages).
+
+```tsx
+import { parseAssessmentStimulusXml } from "@superbuilders/incept-renderer"
+
+const stimulus = parseAssessmentStimulusXml(stimulusXmlString)
+```
+
+**Parameters:**
+- `xml` (string) - Raw QTI 3.0 Assessment Stimulus XML string
+
+**Returns:**
+```tsx
+{
+  identifier: string   // Unique identifier from the XML
+  title: string        // Human-readable title
+  xmlLang: string      // Language code (e.g., "en")
+  bodyHtml: string     // Sanitized HTML content ready for rendering
+}
+```
+
 ---
 
 ### Client Components
@@ -357,6 +381,26 @@ import { QTIRenderer } from "@superbuilders/incept-renderer"
 | `responseFeedback` | `Record<string, { isCorrect: boolean; messageHtml?: string }>` | ❌ | Per-response feedback messages |
 | `theme` | `"duolingo" \| "neobrutalist" \| string` | ❌ | Visual theme (default: `"duolingo"`) |
 
+#### `<QTIStimulusRenderer />`
+
+Renders QTI Assessment Stimuli (reading materials, passages).
+
+```tsx
+import { QTIStimulusRenderer } from "@superbuilders/incept-renderer"
+
+<QTIStimulusRenderer
+  stimulus={parsedStimulus}
+  className="my-8"
+/>
+```
+
+**Props:**
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `stimulus` | `AssessmentStimulus` | ✅ | Parsed stimulus from `parseAssessmentStimulusXml` |
+| `className` | `string` | ❌ | Additional CSS classes for the container |
+
 ---
 
 ### Types
@@ -365,12 +409,15 @@ Import from `@superbuilders/incept-renderer`:
 
 ```tsx
 import type {
+  // Assessment Items (questions)
   DisplayItem,
   DisplayBlock,
   DisplayChoice,
   DisplayChoiceInteraction,
   FormShape,
-  ValidateResult
+  ValidateResult,
+  // Assessment Stimuli (reading materials)
+  AssessmentStimulus
 } from "@superbuilders/incept-renderer"
 ```
 
@@ -435,6 +482,158 @@ interface ValidateResult {
 }
 ```
 
+#### `AssessmentStimulus`
+
+```tsx
+interface AssessmentStimulus {
+  identifier: string   // Unique identifier from the XML
+  title: string        // Human-readable title  
+  xmlLang: string      // Language code (e.g., "en", "es")
+  bodyHtml: string     // Sanitized HTML content
+}
+```
+
+---
+
+## Rendering Stimuli
+
+In addition to assessment items (questions), the package supports rendering **Assessment Stimuli** — reading materials, passages, or articles that provide context for questions.
+
+### What are Stimuli?
+
+QTI Assessment Stimuli (`qti-assessment-stimulus`) are standalone content blocks that contain:
+- Reading passages
+- Articles with images
+- Reference materials
+- Any HTML content that accompanies questions
+
+Unlike assessment items, stimuli have no interactions or correct answers — they're purely display content.
+
+### Parsing Stimulus XML
+
+Use `parseAssessmentStimulusXml` to parse stimulus XML:
+
+```tsx
+import { parseAssessmentStimulusXml } from "@superbuilders/incept-renderer"
+
+const stimulusXml = `<?xml version="1.0" encoding="UTF-8"?>
+<qti-assessment-stimulus 
+  xmlns="http://www.imsglobal.org/xsd/imsqtiasi_v3p0"
+  identifier="stimulus-1" 
+  xml:lang="en" 
+  title="Biodiversity and Ecosystem Health">
+  <qti-stimulus-body>
+    <h2>Biodiversity and ecosystem health</h2>
+    <p><strong>Biodiversity</strong> is the variety of species in an ecosystem.</p>
+    <figure>
+      <img src="coral-reef.jpg" alt="A coral reef" />
+      <figcaption>Coral reef ecosystems have high biodiversity.</figcaption>
+    </figure>
+  </qti-stimulus-body>
+</qti-assessment-stimulus>`
+
+const stimulus = parseAssessmentStimulusXml(stimulusXml)
+// Returns: { identifier, title, xmlLang, bodyHtml }
+```
+
+### Rendering Stimuli
+
+Use the `QTIStimulusRenderer` component to render parsed stimuli:
+
+```tsx
+import { QTIStimulusRenderer, parseAssessmentStimulusXml } from "@superbuilders/incept-renderer"
+
+function ReadingPassage({ xml }: { xml: string }) {
+  const stimulus = parseAssessmentStimulusXml(xml)
+  
+  return (
+    <QTIStimulusRenderer 
+      stimulus={stimulus} 
+      className="my-8"
+    />
+  )
+}
+```
+
+### Server Action Pattern
+
+For Next.js apps, create a server action to parse stimuli:
+
+```tsx
+// lib/qti-actions.ts
+"use server"
+
+import { parseAssessmentStimulusXml } from "@superbuilders/incept-renderer"
+
+export async function parseStimulus(xml: string) {
+  return parseAssessmentStimulusXml(xml)
+}
+```
+
+```tsx
+// app/reading/[id]/page.tsx
+import { parseStimulus } from "@/lib/qti-actions"
+import { QTIStimulusRenderer } from "@superbuilders/incept-renderer"
+
+export default async function ReadingPage({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const xml = await fetchStimulusXml(id) // Your data fetching
+  const stimulus = await parseStimulus(xml)
+  
+  return <QTIStimulusRenderer stimulus={stimulus} />
+}
+```
+
+### Stimulus with Questions
+
+A common pattern is showing a stimulus alongside related questions:
+
+```tsx
+import { QTIStimulusRenderer, QTIRenderer } from "@superbuilders/incept-renderer"
+
+function QuestionWithPassage({ stimulus, item, ...props }) {
+  return (
+    <div className="grid grid-cols-2 gap-8">
+      {/* Reading passage on the left */}
+      <div className="overflow-y-auto max-h-[80vh]">
+        <QTIStimulusRenderer stimulus={stimulus} />
+      </div>
+      
+      {/* Question on the right */}
+      <div>
+        <QTIRenderer item={item} {...props} />
+      </div>
+    </div>
+  )
+}
+```
+
+### AssessmentStimulus Type
+
+```tsx
+interface AssessmentStimulus {
+  identifier: string    // Unique ID from the XML
+  title: string         // Human-readable title
+  xmlLang: string       // Language code (e.g., "en")
+  bodyHtml: string      // Sanitized HTML content
+}
+```
+
+### Supported Content
+
+The stimulus renderer supports:
+- **Headings** (`h1`–`h6`)
+- **Text formatting** (`p`, `strong`, `em`, `b`, `i`, `u`, `sub`, `sup`)
+- **Lists** (`ul`, `ol`, `li`)
+- **Images** (`img`, `figure`, `figcaption`)
+- **Tables** (`table`, `thead`, `tbody`, `tr`, `th`, `td`)
+- **Links** (`a`)
+- **MathML** (mathematical expressions)
+- **Collapsible sections** (`details`, `summary`)
+- **Semantic elements** (`article`, `section`, `blockquote`, `cite`)
+
+All content is sanitized to prevent XSS attacks while preserving safe HTML structure.
+
 ---
 
 ## Theming

package/dist/actions/index.d.ts

@@ -1,4 +1,7 @@
-import { g as DisplayItem, F as FormShape, V as ValidateResult } from '../types-B7YRTQKt.js';
+export { a as parseAssessmentStimulusXml } from '../parser-B8n3iHSM.js';
+import { k as DisplayItem, m as FormShape, V as ValidateResult } from '../schema-DKduufCs.js';
+export { a as AssessmentStimulus } from '../schema-DKduufCs.js';
+import 'zod';
 
 declare function buildDisplayModelFromXml(qtiXml: string): {
     itemKey: string;

package/dist/actions/index.js

@@ -1,10 +1,10 @@
-import { createHash } from 'crypto';
 import * as errors from '@superbuilders/errors';
-import * as logger2 from '@superbuilders/slog';
 import { XMLParser } from 'fast-xml-parser';
 import { z } from 'zod';
+import { createHash } from 'crypto';
+import * as logger2 from '@superbuilders/slog';
 
-// src/actions/internal/display.ts
+// src/parser.ts
 
 // src/html/sanitize.ts
 var DEFAULT_CONFIG = {
@@ -16,6 +16,13 @@ var DEFAULT_CONFIG = {
     "div",
     "br",
     "hr",
+    // Headings
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
     // Formatting
     "b",
     "i",
@@ -65,6 +72,9 @@ var DEFAULT_CONFIG = {
     "figcaption",
     "blockquote",
     "cite",
+    // Interactive
+    "details",
+    "summary",
     // Links
     "a",
     // Forms (for future interactive elements)
@@ -575,6 +585,16 @@ var AssessmentItemSchema = z.object({
   itemBody: ItemBodySchema,
   responseProcessing: ResponseProcessingSchema
 });
+var AssessmentStimulusSchema = z.object({
+  /** Unique identifier for the stimulus */
+  identifier: z.string().min(1),
+  /** Human-readable title */
+  title: z.string().default(""),
+  /** Language code (e.g., "en", "es") */
+  xmlLang: z.string().default("en"),
+  /** The HTML content of the stimulus body */
+  bodyHtml: z.string()
+});
 
 // src/parser.ts
 function createXmlParser() {
@@ -1200,8 +1220,47 @@ function parseAssessmentItemXml(xml) {
   }
   return validation.data;
 }
-
-// src/actions/internal/display.ts
+function parseAssessmentStimulusXml(xml) {
+  if (!xml || typeof xml !== "string") {
+    throw errors.new("xml input must be a non-empty string");
+  }
+  const parser = createXmlParser();
+  const parseResult = errors.trySync(() => {
+    return parser.parse(xml, true);
+  });
+  if (parseResult.error) {
+    throw errors.wrap(parseResult.error, "xml parse");
+  }
+  const raw = parseResult.data;
+  if (!Array.isArray(raw)) {
+    throw errors.new("expected xml parser to output an array for preserveOrder");
+  }
+  const normalizedTree = raw.map(normalizeNode).filter((n) => typeof n !== "string");
+  const rootNode = normalizedTree.find(
+    (n) => n.tagName === "qti-assessment-stimulus" || n.tagName.endsWith("assessment-stimulus")
+  );
+  if (!rootNode) {
+    throw errors.new("qti assessment stimulus not found in xml document");
+  }
+  const rootChildren = rootNode.children.filter((c) => typeof c !== "string");
+  const stimulusBodyNode = rootChildren.find((n) => n.tagName === "qti-stimulus-body");
+  if (!stimulusBodyNode) {
+    throw errors.new("qti-stimulus-body not found in stimulus document");
+  }
+  const bodyHtml = getInnerHtml(stimulusBodyNode);
+  const normalizedStimulus = {
+    identifier: coerceString(rootNode.attrs.identifier),
+    title: coerceString(rootNode.attrs.title),
+    xmlLang: coerceString(rootNode.attrs["xml:lang"]) || coerceString(rootNode.attrs["xml-lang"]) || "en",
+    bodyHtml
+  };
+  const validation = AssessmentStimulusSchema.safeParse(normalizedStimulus);
+  if (!validation.success) {
+    const errorDetails = validation.error.issues.map((err) => `${err.path.join(".")}: ${err.message}`).join("; ");
+    throw errors.new(`qti stimulus validation: ${errorDetails}`);
+  }
+  return validation.data;
+}
 function shuffleArray(items) {
   const arr = items.slice();
   for (let i = arr.length - 1; i > 0; i--) {
@@ -1688,6 +1747,6 @@ async function validateResponsesSecure(qtiXml, responses) {
   return validateResponsesFromXml(qtiXml, responses);
 }
 
-export { buildDisplayModel, buildDisplayModelFromXml, validateResponsesFromXml, validateResponsesSecure };
+export { buildDisplayModel, buildDisplayModelFromXml, parseAssessmentStimulusXml, validateResponsesFromXml, validateResponsesSecure };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map