tessera-learn 0.0.8 → 0.0.10

package/src/components/MultipleChoice.svelte

@@ -1,5 +1,5 @@
 <script>
-  import { getContext, onMount } from 'svelte';
+  import { onMount } from 'svelte';
   import { useQuestion } from '../runtime/hooks.svelte.js';
   import { slugFromQuestion } from './util.js';
   import LockedBanner from './LockedBanner.svelte';
@@ -17,15 +17,12 @@
     weight = 1,
   } = $props();
 
-  const quiz = getContext('tessera-quiz');
-  const standalone = !quiz;
-
   let selectedOption = $state(null);
 
   const componentId = $props.id();
   const groupId = `mc-${componentId}`;
 
-  const handle = useQuestion({
+  const q = useQuestion({
     get id() { return id ?? `mc-${slugFromQuestion(question)}`; },
     get weight() { return weight; },
     get maxRetries() { return maxRetries; },
@@ -37,21 +34,21 @@
     reset: () => { selectedOption = null; },
   });
 
-  const myIndex = $derived(handle.quizIndex ?? -1);
+  // `q.mode` is fixed for the lifetime of the widget; capture once.
+  const inQuiz = q.mode === 'quiz';
 
   onMount(() => {
-    if (!standalone) quiz.setRender(myIndex, renderQuestion);
+    if (inQuiz) q.setRender(renderQuestion);
   });
 
   function handleSelect(optIndex) {
-    if (standalone) {
-      if (handle.submitted) return;
-      selectedOption = optIndex;
-      handle.submit();
+    if (q.locked) return;
+    selectedOption = optIndex;
+    if (inQuiz) {
+      q.setAnswer(optIndex);
+      q.commit();
     } else {
-      if (quizLocked) return;
-      selectedOption = optIndex;
-      quiz.setAnswer(myIndex, optIndex);
+      q.submit();
     }
   }
 
@@ -59,26 +56,16 @@
     return optIndex === correct;
   }
 
-  // Quiz-mode helpers
   function getOptionClass(optIndex) {
-    if (standalone) {
-      if (!handle.submitted) return '';
-      if (isCorrectOption(optIndex)) return 'correct';
-      if (optIndex === selectedOption && !isCorrectOption(optIndex)) return 'incorrect';
-      return '';
-    }
-    if (!quiz.feedbackVisible(myIndex)) return '';
-    const answer = quiz.getAnswer(myIndex);
+    if (!q.feedbackVisible) return '';
+    const answer = inQuiz ? q.answer : selectedOption;
     if (isCorrectOption(optIndex)) return 'correct';
     if (optIndex === answer && !isCorrectOption(optIndex)) return 'incorrect';
     return '';
   }
-
-  let isLocked = $derived(standalone ? false : quiz.isLockedCorrect(myIndex));
-  let quizLocked = $derived(standalone ? handle.submitted : quiz.isAnswerLocked(myIndex));
 </script>
 
-{#if standalone}
+{#if !inQuiz}
   <div class="tessera-mc" role="radiogroup" aria-labelledby="{groupId}-label">
     <p class="tessera-mc-question" id="{groupId}-label">{question}</p>
 
@@ -98,13 +85,13 @@
             name={groupId}
             value={i}
             checked={isSelected}
-            disabled={handle.submitted}
+            disabled={q.submitted}
             onchange={() => handleSelect(i)}
           />
           <span class="tessera-mc-radio-custom"></span>
           <span class="tessera-mc-option-text">{option}</span>
 
-          {#if handle.submitted}
+          {#if q.submitted}
             {#if stateClass === 'correct' && (correctFeedback || optionFeedback[i])}
               <span class="tessera-mc-feedback correct">{optionFeedback[i] || correctFeedback}</span>
             {:else if stateClass === 'incorrect' && (incorrectFeedback || optionFeedback[i])}
@@ -117,14 +104,14 @@
       {/each}
     </div>
 
-    {#if handle.submitted}
+    {#if q.submitted}
       {#if selectedOption === correct && correctFeedback && !optionFeedback[selectedOption]}
         <div class="tessera-mc-overall-feedback correct">{correctFeedback}</div>
       {:else if selectedOption !== correct && incorrectFeedback && !optionFeedback[selectedOption]}
         <div class="tessera-mc-overall-feedback incorrect">{incorrectFeedback}</div>
       {/if}
-      {#if handle.canRetry}
-        <RetryButton onclick={() => handle.retry()} />
+      {#if q.canRetry}
+        <RetryButton onclick={() => q.retry()} />
       {/if}
     {/if}
   </div>
@@ -132,7 +119,7 @@
 
 {#snippet renderQuestion()}
   <div class="tessera-mc" role="radiogroup" aria-labelledby="{groupId}-label">
-    {#if isLocked}
+    {#if q.isLockedCorrect}
       <LockedBanner />
     {/if}
     <p class="tessera-mc-question" id="{groupId}-label">{question}</p>
@@ -140,7 +127,7 @@
     <div class="tessera-mc-options">
       {#each options as option, i}
         {@const optionId = `${groupId}-opt-${i}`}
-        {@const isSelected = (quizLocked ? quiz.getAnswer(myIndex) : selectedOption) === i}
+        {@const isSelected = (q.locked ? q.answer : selectedOption) === i}
         {@const stateClass = getOptionClass(i)}
         <label
           class="tessera-mc-option {stateClass}"
@@ -153,13 +140,13 @@
             name={groupId}
             value={i}
             checked={isSelected}
-            disabled={quizLocked}
+            disabled={q.locked}
             onchange={() => handleSelect(i)}
           />
           <span class="tessera-mc-radio-custom"></span>
           <span class="tessera-mc-option-text">{option}</span>
 
-          {#if quiz.feedbackVisible(myIndex)}
+          {#if q.feedbackVisible}
             {#if stateClass === 'correct' && (correctFeedback || optionFeedback[i])}
               <span class="tessera-mc-feedback correct">{optionFeedback[i] || correctFeedback}</span>
             {:else if stateClass === 'incorrect' && (incorrectFeedback || optionFeedback[i])}
@@ -172,8 +159,8 @@
       {/each}
     </div>
 
-    {#if quiz.feedbackVisible(myIndex)}
-      {@const answer = quiz.getAnswer(myIndex)}
+    {#if q.feedbackVisible}
+      {@const answer = q.answer}
       {#if answer === correct && correctFeedback && !optionFeedback[answer]}
         <div class="tessera-mc-overall-feedback correct">{correctFeedback}</div>
       {:else if answer !== correct && incorrectFeedback && !optionFeedback[answer]}

package/src/components/Quiz.svelte

@@ -9,37 +9,35 @@
 
   const pageCtx = getContext('tessera-page');
   let quizConfig = $derived(pageCtx?.quiz ?? {});
-  let passingScore = $derived(pageCtx?.passingScore ?? 70);
-  let showFeedback = $derived(quizConfig.showFeedback ?? true);
+  let feedbackDisabled = $derived(quizConfig.feedbackMode === 'never');
   let maxAttempts = $derived(quizConfig.maxAttempts ?? Infinity);
-  let isImmediateMode = $derived(showFeedback && quizConfig.feedbackMode === 'immediate');
+  let isImmediateMode = $derived(!feedbackDisabled && quizConfig.feedbackMode === 'immediate');
 
   let currentQuestionIndex = $state(0);
   let reviewIndex = $state(0);
 
   let totalQuestions = $derived(handle.questions.length);
+  let currentQuestion = $derived(handle.questions[currentQuestionIndex]);
+  let reviewQuestion = $derived(handle.questions[reviewIndex]);
   let correctCount = $derived(
     handle.questions.reduce((sum, q) => sum + (q.correct ? 1 : 0), 0)
   );
-  let passed = $derived(handle.score >= passingScore);
+  let passed = $derived(handle.score >= handle.passingScore);
 
-  function isAnswered(i) {
-    return handle.getAnswer(i) !== undefined || handle.isLockedCorrect(i);
+  function isAnswered(q) {
+    if (!q) return false;
+    return q.answer !== undefined || q.isLockedCorrect;
   }
 
-  function needsReveal(i) {
-    return (
-      isImmediateMode &&
-      isAnswered(i) &&
-      !handle.isLockedCorrect(i) &&
-      !handle.feedbackVisible(i)
-    );
+  function needsReveal(q) {
+    if (!q) return false;
+    return isImmediateMode && isAnswered(q) && !q.isLockedCorrect && !q.feedbackVisible;
   }
 
   function goNextQuestion() {
     // Immediate-mode: first click reveals feedback, second advances.
-    if (needsReveal(currentQuestionIndex)) {
-      handle.revealFeedback(currentQuestionIndex);
+    if (needsReveal(currentQuestion)) {
+      handle.revealFeedback(currentQuestion);
       return;
     }
     if (currentQuestionIndex < totalQuestions - 1) {
@@ -94,10 +92,9 @@
 
     <div class="tessera-quiz-questions">
       {#each handle.questions as q, i (q.id)}
-        {@const render = handle.getRender(i)}
         <div class="tessera-quiz-question-wrapper" class:active={i === currentQuestionIndex} aria-hidden={i !== currentQuestionIndex}>
-          {#if render}
-            {@render render()}
+          {#if q.render}
+            {@render q.render()}
           {/if}
         </div>
       {/each}
@@ -114,15 +111,15 @@
       {#if currentQuestionIndex < totalQuestions - 1}
         <button
           class="tessera-quiz-btn tessera-btn-primary"
-          disabled={!isAnswered(currentQuestionIndex)}
+          disabled={!isAnswered(currentQuestion)}
           onclick={goNextQuestion}
         >
-          {handle.feedbackVisible(currentQuestionIndex) && isImmediateMode ? 'Continue' : 'Next'}
+          {currentQuestion?.feedbackVisible && isImmediateMode ? 'Continue' : 'Next'}
         </button>
-      {:else if needsReveal(currentQuestionIndex)}
+      {:else if needsReveal(currentQuestion)}
         <button
           class="tessera-quiz-btn tessera-btn-primary"
-          onclick={() => handle.revealFeedback(currentQuestionIndex)}
+          onclick={() => handle.revealFeedback(currentQuestion)}
         >
           Check Answer
         </button>
@@ -148,10 +145,9 @@
 
     <div class="tessera-quiz-questions">
       {#each handle.questions as q, i (q.id)}
-        {@const render = handle.getRender(i)}
         <div class="tessera-quiz-question-wrapper" class:active={i === reviewIndex} aria-hidden={i !== reviewIndex}>
-          {#if render}
-            {@render render()}
+          {#if q.render}
+            {@render q.render()}
           {/if}
         </div>
       {/each}
@@ -197,7 +193,7 @@
       </p>
 
       <div class="tessera-quiz-results-actions">
-        {#if showFeedback}
+        {#if !feedbackDisabled}
           <button
             class="tessera-quiz-btn tessera-quiz-btn-secondary"
             onclick={handleStartReview}

package/src/components/Sorting.svelte

@@ -1,5 +1,5 @@
 <script>
-  import { getContext, onMount } from 'svelte';
+  import { onMount } from 'svelte';
   import { SvelteMap } from 'svelte/reactivity';
   import { useQuestion } from '../runtime/hooks.svelte.js';
   import { slugFromQuestion, shuffle } from './util.js';
@@ -19,9 +19,6 @@
     weight = 1,
   } = $props();
 
-  const quiz = getContext('tessera-quiz');
-  const standalone = !quiz;
-
   let queue = $state([]);              // item indices not yet placed; queue[0] is current
   let placements = $state(new SvelteMap()); // itemIdx → targetIdx
   let dragOver = $state(null);         // target index highlighted during drag
@@ -36,15 +33,6 @@
     isDragging = false;
   }
 
-  if (standalone) {
-    initQueue();
-  } else {
-    onMount(() => {
-      initQueue();
-      quiz.setRender(myIndex, renderQuestion);
-    });
-  }
-
   function checkAnswer(answer) {
     if (!answer || !(answer instanceof Map)) return false;
     if (answer.size !== items.length) return false;
@@ -61,7 +49,7 @@
   // Sorting is semantically a categorization (each item → one target) and maps
   // cleanly to SCORM 2004's `matching` interaction. We emit [itemIdx, targetIdx]
   // pairs as stringified ids.
-  const handle = useQuestion({
+  const q = useQuestion({
     get id() { return id ?? `sorting-${slugFromQuestion(question)}`; },
     get weight() { return weight; },
     get maxRetries() { return maxRetries; },
@@ -73,13 +61,20 @@
     reset: resetState,
   });
 
-  const myIndex = $derived(handle.quizIndex ?? -1);
+  // `q.mode` is fixed for the lifetime of the widget; capture it once so
+  // setup-time branches don't trip Svelte's "state_referenced_locally" warning.
+  const inQuiz = q.mode === 'quiz';
 
-  let currentItemIdx = $derived(queue.length > 0 ? queue[0] : null);
+  if (!inQuiz) {
+    initQueue();
+  } else {
+    onMount(() => {
+      initQueue();
+      q.setRender(renderQuestion);
+    });
+  }
 
-  let isLocked = $derived(standalone ? false : quiz.isLockedCorrect(myIndex));
-  let isDisabled = $derived(standalone ? handle.submitted : quiz.isAnswerLocked(myIndex));
-  let showFeedback = $derived(standalone ? handle.submitted : quiz.feedbackVisible(myIndex));
+  let currentItemIdx = $derived(queue.length > 0 ? queue[0] : null);
 
   function getItemsForTarget(targetIdx) {
     const result = [];
@@ -94,19 +89,22 @@
   }
 
   function placeCard(targetIdx) {
-    if (isDisabled || currentItemIdx === null) return;
+    if (q.locked || currentItemIdx === null) return;
     const itemIdx = queue[0];
     placements.set(itemIdx, targetIdx);
     queue = queue.slice(1);
     cardSelected = false;
-    if (!standalone) quiz.setAnswer(myIndex, new Map(placements));
+    if (inQuiz) {
+      q.setAnswer(new Map(placements));
+      if (placements.size === items.length) q.commit();
+    }
   }
 
   function returnCard(itemIdx) {
-    if (isDisabled) return;
+    if (q.locked) return;
     placements.delete(itemIdx);
     queue = [itemIdx, ...queue];
-    if (!standalone) quiz.setAnswer(myIndex, new Map(placements));
+    if (inQuiz) q.setAnswer(new Map(placements));
   }
 
   // --- Drag handlers ---
@@ -122,7 +120,7 @@
   }
 
   function onDragOver(e, targetIdx) {
-    if (isDisabled) return;
+    if (q.locked) return;
     e.preventDefault();
     e.dataTransfer.dropEffect = 'move';
     dragOver = targetIdx;
@@ -145,7 +143,7 @@
   // --- Click / tap handlers ---
 
   function onCardClick() {
-    if (isDisabled || currentItemIdx === null) return;
+    if (q.locked || currentItemIdx === null) return;
     cardSelected = !cardSelected;
   }
 
@@ -157,7 +155,7 @@
   }
 
   function onTargetClick(targetIdx) {
-    if (isDisabled || !cardSelected) return;
+    if (q.locked || !cardSelected) return;
     placeCard(targetIdx);
   }
 
@@ -174,7 +172,7 @@
   <p class="tessera-sorting-question">{question}</p>
 
   <!-- Card deck: shows the current card to be placed -->
-  {#if !isDisabled}
+  {#if !q.locked}
     <div class="tessera-sorting-deck" aria-live="polite" aria-atomic="false">
       {#if currentItemIdx !== null}
         <div class="tessera-sorting-deck-inner">
@@ -212,17 +210,17 @@
   {/if}
 
   <!-- Drop targets -->
-  <div class="tessera-sorting-targets" class:targets-active={cardSelected && !isDisabled}>
+  <div class="tessera-sorting-targets" class:targets-active={cardSelected && !q.locked}>
     {#each targets as targetLabel, targetIdx}
       {@const targetItems = getItemsForTarget(targetIdx)}
       <div
         class="tessera-sorting-target"
         class:drag-over={dragOver === targetIdx}
-        class:clickable={cardSelected && !isDisabled}
+        class:clickable={cardSelected && !q.locked}
         role="button"
         tabindex="0"
-        aria-disabled={!(cardSelected && !isDisabled)}
-        aria-label="Target: {targetLabel}{cardSelected && !isDisabled ? ` (activate to place ${items[currentItemIdx]})` : ''}"
+        aria-disabled={!(cardSelected && !q.locked)}
+        aria-label="Target: {targetLabel}{cardSelected && !q.locked ? ` (activate to place ${items[currentItemIdx]})` : ''}"
         ondragover={(e) => onDragOver(e, targetIdx)}
         ondragleave={onDragLeave}
         ondrop={(e) => onDrop(e, targetIdx)}
@@ -235,17 +233,17 @@
             {#each targetItems as itemIdx}
               <div
                 class="tessera-sorting-placed-item"
-                class:correct={showFeedback && isCorrectPlacement(itemIdx)}
-                class:incorrect={showFeedback && !isCorrectPlacement(itemIdx)}
+                class:correct={q.feedbackVisible && isCorrectPlacement(itemIdx)}
+                class:incorrect={q.feedbackVisible && !isCorrectPlacement(itemIdx)}
               >
                 <span class="tessera-sorting-item-text">{items[itemIdx]}</span>
-                {#if !isDisabled}
+                {#if !q.locked}
                   <button
                     class="tessera-sorting-remove"
                     aria-label="Return '{items[itemIdx]}' to deck"
                     onclick={(e) => { e.stopPropagation(); returnCard(itemIdx); }}
                   >×</button>
-                {:else if showFeedback}
+                {:else if q.feedbackVisible}
                   <span class="tessera-sorting-item-icon" aria-hidden="true">
                     {isCorrectPlacement(itemIdx) ? '✓' : '✗'}
                   </span>
@@ -259,7 +257,7 @@
   </div>
 
   <!-- Feedback (shown after standalone submit or quiz feedbackVisible) -->
-  {#if showFeedback}
+  {#if q.feedbackVisible}
     {@const isCorrect = checkAnswer(placements)}
     <div class="tessera-sorting-review">
       {#if isCorrect}
@@ -285,23 +283,23 @@
           <p class="tessera-sorting-feedback incorrect">{incorrectFeedback}</p>
         {/if}
       {/if}
-      {#if standalone && handle.canRetry}
-        <RetryButton onclick={() => handle.retry()} />
+      {#if !inQuiz && q.canRetry}
+        <RetryButton onclick={() => q.retry()} />
       {/if}
     </div>
   {/if}
 
   <!-- Standalone Check button (shown once all cards are placed) -->
-  {#if standalone && !handle.submitted && placements.size === items.length}
+  {#if !inQuiz && !q.submitted && placements.size === items.length}
     <div class="tessera-sorting-actions">
-      <button class="tessera-btn-primary tessera-sorting-check" onclick={() => handle.submit()}>
+      <button class="tessera-btn-primary tessera-sorting-check" onclick={() => q.submit()}>
         Check Answer
       </button>
     </div>
   {/if}
 {/snippet}
 
-{#if standalone}
+{#if !inQuiz}
   <div class="tessera-sorting" aria-label={question}>
     {@render sortingContent()}
   </div>
@@ -309,7 +307,7 @@
 
 {#snippet renderQuestion()}
   <div class="tessera-sorting" aria-label={question}>
-    {#if isLocked}
+    {#if q.isLockedCorrect}
       <LockedBanner />
     {/if}
     {@render sortingContent()}

package/src/index.ts

@@ -48,6 +48,7 @@ export type {
   UseQuestionOptions,
   UseQuestionHandle,
   UseQuizHandle,
+  Question,
 } from './runtime/hooks.svelte.js';
 export type {
   XAPIConfig,