@superbuilders/incept-renderer 0.1.0

package/README.md

@@ -0,0 +1,170 @@
+# @alpha/qti-renderer
+
+A QTI 3.0 Assessment Renderer for React applications. Parse, validate, and render QTI XML with customizable themes.
+
+## Features
+
+- 📝 **QTI 3.0 Support** - Parse and render QTI 3.0 assessment items
+- 🎨 **Themeable** - Built-in Duolingo and Neobrutalist themes, or create your own
+- 🔒 **Secure** - Server-side parsing and validation keeps correct answers hidden
+- ⚛️ **React 18/19** - Works with latest React and Next.js
+- 📦 **Tree-shakeable** - Only import what you need
+
+## Installation
+
+```bash
+npm install @alpha/qti-renderer
+# or
+bun add @alpha/qti-renderer
+```
+
+## Quick Start
+
+### 1. Parse QTI XML (Server-side)
+
+```tsx
+// app/quiz/[id]/page.tsx (Server Component)
+import { parseAssessmentItemXml, validateResponse } from "@alpha/qti-renderer/server"
+import { QTIRenderer } from "@alpha/qti-renderer"
+import "@alpha/qti-renderer/themes/duolingo.css"
+
+export default async function QuizPage({ params }) {
+  // Fetch and parse QTI XML on the server
+  const xml = await fetchQTIFromDatabase(params.id)
+  const { item } = await parseAssessmentItemXml(xml)
+
+  // Create server action for validation
+  async function checkAnswer(responses: Record<string, string[]>) {
+    "use server"
+    return validateResponse(item, responses)
+  }
+
+  return <QuizClient item={item} onValidate={checkAnswer} />
+}
+```
+
+### 2. Render and Handle Interactions (Client-side)
+
+```tsx
+// app/quiz/[id]/client.tsx
+"use client"
+
+import { useState } from "react"
+import { QTIRenderer } from "@alpha/qti-renderer"
+import type { AssessmentItem } from "@alpha/qti-renderer"
+
+interface Props {
+  item: AssessmentItem
+  onValidate: (responses: Record<string, string[]>) => Promise<ValidationResult>
+}
+
+export function QuizClient({ item, onValidate }: Props) {
+  const [responses, setResponses] = useState<Record<string, string[]>>({})
+  const [feedback, setFeedback] = useState(null)
+  const [showFeedback, setShowFeedback] = useState(false)
+
+  const handleCheck = async () => {
+    const result = await onValidate(responses)
+    setFeedback(result)
+    setShowFeedback(true)
+  }
+
+  return (
+    <div>
+      <QTIRenderer
+        item={item}
+        theme="duolingo"
+        responses={responses}
+        onResponseChange={(id, values) =>
+          setResponses(prev => ({ ...prev, [id]: values }))
+        }
+        showFeedback={showFeedback}
+        feedback={feedback}
+      />
+
+      <button onClick={handleCheck}>Check Answer</button>
+    </div>
+  )
+}
+```
+
+## Themes
+
+### Built-in Themes
+
+Import the CSS for your chosen theme:
+
+```tsx
+// Duolingo-style (rounded, friendly)
+import "@alpha/qti-renderer/themes/duolingo.css"
+
+// Neobrutalist (bold, sharp)
+import "@alpha/qti-renderer/themes/neobrutalist.css"
+
+// Base only (minimal styling)
+import "@alpha/qti-renderer/themes/base.css"
+```
+
+Then set the theme prop:
+
+```tsx
+<QTIRenderer theme="duolingo" ... />
+<QTIRenderer theme="neobrutalist" ... />
+```
+
+### Custom Themes
+
+Create your own theme by overriding CSS variables:
+
+```css
+[data-qti-theme="my-theme"] {
+  --qti-container-bg: #1a1a2e;
+  --qti-container-border: #ffffff;
+  --qti-choice-selected-bg: #ff6b6b;
+  /* ... see base.css for all variables */
+}
+```
+
+## API Reference
+
+### `<QTIRenderer />`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `item` | `AssessmentItem` | The parsed QTI assessment item |
+| `theme` | `string` | Theme name (default: "duolingo") |
+| `responses` | `Record<string, string[]>` | Current user responses |
+| `onResponseChange` | `(id, values) => void` | Called when user changes response |
+| `showFeedback` | `boolean` | Whether to show feedback |
+| `feedback` | `ResponseFeedback` | Overall feedback data |
+| `disabled` | `boolean` | Disable all interactions |
+
+### `parseAssessmentItemXml(xml)`
+
+Parses QTI XML into an `AssessmentItem`. Server-side only.
+
+```ts
+const { success, item, error } = await parseAssessmentItemXml(xml)
+```
+
+### `validateResponse(item, responses)`
+
+Validates user responses against correct answers. Server-side only.
+
+```ts
+const result = await validateResponse(item, responses)
+// { isCorrect, responses, feedbackHtml, score, maxScore }
+```
+
+## Supported Interaction Types
+
+- ✅ Choice Interaction (single & multiple)
+- ✅ Inline Choice Interaction (dropdowns)
+- ✅ Text Entry Interaction
+- 🚧 Order Interaction
+- 🚧 Gap Match Interaction
+- 🚧 Match Interaction
+
+## License
+
+MIT

package/dist/actions/index.d.ts

@@ -0,0 +1,27 @@
+import { D as DisplayItem, F as FormShape, V as ValidateResult } from '../types-MOyn9ktl.js';
+
+declare function buildDisplayModelFromXml(qtiXml: string): {
+    itemKey: string;
+    item: DisplayItem;
+    shape: FormShape;
+};
+
+/**
+ * Parses QTI XML and builds a display model for rendering.
+ * This is a server action - call it from the server to keep XML processing secure.
+ */
+declare function buildDisplayModel(qtiXml: string): Promise<{
+    itemKey: string;
+    item: DisplayItem;
+    shape: FormShape;
+}>;
+
+declare function validateResponsesFromXml(qtiXml: string, responses: Record<string, string | string[]>): ValidateResult;
+
+/**
+ * Validates user responses against the QTI XML.
+ * This is a server action - call it from the server to keep correct answers secure.
+ */
+declare function validateResponsesSecure(qtiXml: string, responses: Record<string, string | string[]>): Promise<ValidateResult>;
+
+export { DisplayItem, FormShape, ValidateResult, buildDisplayModel, buildDisplayModelFromXml, validateResponsesFromXml, validateResponsesSecure };