tessera-learn 0.0.8 → 0.0.9

package/src/components/FillInTheBlank.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,9 +17,6 @@
     weight = 1,
   } = $props();
 
-  const quiz = getContext('tessera-quiz');
-  const standalone = !quiz;
-
   let inputValue = $state('');
 
   const componentId = $props.id();
@@ -35,7 +32,7 @@
     });
   }
 
-  const handle = useQuestion({
+  const q = useQuestion({
     get id() { return id ?? `fitb-${slugFromQuestion(question)}`; },
     get weight() { return weight; },
     get maxRetries() { return maxRetries; },
@@ -48,36 +45,33 @@
     reset: () => { inputValue = ''; },
   });
 
-  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);
   });
 
-  let isLocked = $derived(standalone ? false : quiz.isLockedCorrect(myIndex));
-  let quizLocked = $derived(standalone ? handle.submitted : quiz.isAnswerLocked(myIndex));
-
   function handleInput(e) {
-    if (standalone) {
-      if (handle.submitted) return;
-      inputValue = e.target.value;
-    } else {
-      if (quizLocked) return;
-      inputValue = e.target.value;
-      quiz.setAnswer(myIndex, inputValue);
-    }
+    if (q.locked) return;
+    inputValue = e.target.value;
+    if (inQuiz) q.setAnswer(inputValue);
+  }
+
+  function handleBlur() {
+    if (!inQuiz || q.locked) return;
+    if (inputValue.trim()) q.commit();
   }
 
   function handleKeydown(e) {
-    if (!standalone || handle.submitted) return;
+    if (inQuiz || q.submitted) return;
     if (e.key === 'Enter' && inputValue.trim()) {
-      handle.submit();
+      q.submit();
     }
   }
-
 </script>
 
-{#if standalone}
+{#if !inQuiz}
   <div class="tessera-fitb">
     <label class="tessera-fitb-question" for={inputId}>{question}</label>
 
@@ -86,27 +80,27 @@
         type="text"
         id={inputId}
         class="tessera-fitb-input"
-        class:correct={handle.submitted && checkAnswer(inputValue)}
-        class:incorrect={handle.submitted && !checkAnswer(inputValue)}
+        class:correct={q.submitted && checkAnswer(inputValue)}
+        class:incorrect={q.submitted && !checkAnswer(inputValue)}
         value={inputValue}
         oninput={handleInput}
         onkeydown={handleKeydown}
-        disabled={handle.submitted}
+        disabled={q.submitted}
         placeholder="Type your answer..."
         autocomplete="off"
       />
-      {#if !handle.submitted}
+      {#if !q.submitted}
         <button
           class="tessera-btn-primary tessera-fitb-check-btn"
           disabled={!inputValue.trim()}
-          onclick={() => { handle.submit(); }}
+          onclick={() => { q.submit(); }}
         >
           Check
         </button>
       {/if}
     </div>
 
-    {#if handle.submitted}
+    {#if q.submitted}
       {@const isCorrect = checkAnswer(inputValue)}
       <div class="tessera-fitb-review">
         {#if isCorrect}
@@ -129,8 +123,8 @@
             <p class="tessera-fitb-feedback incorrect">{incorrectFeedback}</p>
           {/if}
         {/if}
-        {#if handle.canRetry}
-          <RetryButton onclick={() => handle.retry()} />
+        {#if q.canRetry}
+          <RetryButton onclick={() => q.retry()} />
         {/if}
       </div>
     {/if}
@@ -139,7 +133,7 @@
 
 {#snippet renderQuestion()}
   <div class="tessera-fitb">
-    {#if isLocked}
+    {#if q.isLockedCorrect}
       <LockedBanner />
     {/if}
     <label class="tessera-fitb-question" for={inputId}>{question}</label>
@@ -149,18 +143,19 @@
         type="text"
         id={inputId}
         class="tessera-fitb-input"
-        class:correct={quiz.feedbackVisible(myIndex) && checkAnswer(quiz.getAnswer(myIndex))}
-        class:incorrect={quiz.feedbackVisible(myIndex) && !checkAnswer(quiz.getAnswer(myIndex))}
-        value={quizLocked ? (quiz.getAnswer(myIndex) ?? '') : inputValue}
+        class:correct={q.feedbackVisible && checkAnswer(q.answer)}
+        class:incorrect={q.feedbackVisible && !checkAnswer(q.answer)}
+        value={q.locked ? (q.answer ?? '') : inputValue}
         oninput={handleInput}
-        disabled={quizLocked}
+        onblur={handleBlur}
+        disabled={q.locked}
         placeholder="Type your answer..."
         autocomplete="off"
       />
     </div>
 
-    {#if quiz.feedbackVisible(myIndex)}
-      {@const userAnswer = quiz.getAnswer(myIndex)}
+    {#if q.feedbackVisible}
+      {@const userAnswer = q.answer}
       {@const isCorrect = checkAnswer(userAnswer)}
       <div class="tessera-fitb-review">
         {#if isCorrect}

package/src/components/Matching.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';
@@ -17,9 +17,6 @@
     weight = 1,
   } = $props();
 
-  const quiz = getContext('tessera-quiz');
-  const standalone = !quiz;
-
   let shuffledRight = $state([]);
   let matches = $state(new SvelteMap());
   // Reverse index (right.originalIndex → left index) for O(1) right-column lookups.
@@ -27,7 +24,6 @@
   let selectedLeft = $state(null);
   let selectedRight = $state(null);
 
-
   const pairColors = [
     '#2563eb', '#9333ea', '#0891b2', '#c2410c', '#4f46e5',
     '#0d9488', '#b91c1c', '#7c3aed', '#0369a1', '#a16207',
@@ -37,15 +33,6 @@
     shuffledRight = shuffle(pairs.map((p, i) => ({ text: p.right, originalIndex: i })));
   }
 
-  if (standalone) {
-    initShuffle();
-  } else {
-    onMount(() => {
-      initShuffle();
-      quiz.setRender(myIndex, renderQuestion);
-    });
-  }
-
   function checkAnswer(answer) {
     if (!answer || !(answer instanceof Map)) return false;
     if (answer.size !== pairs.length) return false;
@@ -63,7 +50,7 @@
     initShuffle();
   }
 
-  const handle = useQuestion({
+  const q = useQuestion({
     get id() { return id ?? `matching-${slugFromQuestion(question)}`; },
     get weight() { return weight; },
     get maxRetries() { return maxRetries; },
@@ -75,47 +62,37 @@
     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 isLocked = $derived(standalone ? false : quiz.isLockedCorrect(myIndex));
-  let quizLocked = $derived(standalone ? handle.submitted : quiz.isAnswerLocked(myIndex));
+  if (!inQuiz) {
+    initShuffle();
+  } else {
+    onMount(() => {
+      initShuffle();
+      q.setRender(renderQuestion);
+    });
+  }
 
   function handleLeftClick(leftIndex) {
-    if (standalone) {
-      if (handle.submitted) return;
-    } else {
-      if (quizLocked) return;
-    }
-
+    if (q.locked) return;
     if (selectedLeft === leftIndex) {
       selectedLeft = null;
       return;
     }
-
     selectedLeft = leftIndex;
-
-    if (selectedRight !== null) {
-      createMatch(leftIndex, selectedRight);
-    }
+    if (selectedRight !== null) createMatch(leftIndex, selectedRight);
   }
 
   function handleRightClick(rightOriginalIndex) {
-    if (standalone) {
-      if (handle.submitted) return;
-    } else {
-      if (quizLocked) return;
-    }
-
+    if (q.locked) return;
     if (selectedRight === rightOriginalIndex) {
       selectedRight = null;
       return;
     }
-
     selectedRight = rightOriginalIndex;
-
-    if (selectedLeft !== null) {
-      createMatch(selectedLeft, selectedRight);
-    }
+    if (selectedLeft !== null) createMatch(selectedLeft, selectedRight);
   }
 
   function createMatch(leftIndex, rightOriginalIndex) {
@@ -134,27 +111,20 @@
     selectedLeft = null;
     selectedRight = null;
 
-    if (standalone) {
-      if (matches.size === pairs.length && !handle.submitted) {
-        handle.submit();
-      }
-    } else {
-      quiz.setAnswer(myIndex, new Map(matches));
+    if (inQuiz) {
+      q.setAnswer(new Map(matches));
+      if (matches.size === pairs.length) q.commit();
+    } else if (matches.size === pairs.length && !q.submitted) {
+      q.submit();
     }
   }
 
   function removeMatch(leftIndex) {
-    if (standalone) {
-      if (handle.submitted) return;
-    } else {
-      if (quizLocked) return;
-    }
+    if (q.locked) return;
     const right = matches.get(leftIndex);
     matches.delete(leftIndex);
     if (right !== undefined) rightToLeft.delete(right);
-    if (!standalone) {
-      quiz.setAnswer(myIndex, new Map(matches));
-    }
+    if (inQuiz) q.setAnswer(new Map(matches));
   }
 
   function getMatchColor(leftIndex) {
@@ -178,9 +148,6 @@
   function isMatchCorrect(leftIndex) {
     return matches.get(leftIndex) === leftIndex;
   }
-
-  let showFeedback = $derived(standalone ? handle.submitted : quiz.feedbackVisible(myIndex));
-  let isDisabled = $derived(standalone ? handle.submitted : quizLocked);
 </script>
 
 {#snippet matchingContent()}
@@ -194,8 +161,8 @@
         {@const color = getMatchColor(i)}
         {@const isSelected = selectedLeft === i}
         {@const matched = matches.has(i)}
-        {@const correctMatch = showFeedback && matched && isMatchCorrect(i)}
-        {@const wrongMatch = showFeedback && matched && !isMatchCorrect(i)}
+        {@const correctMatch = q.feedbackVisible && matched && isMatchCorrect(i)}
+        {@const wrongMatch = q.feedbackVisible && matched && !isMatchCorrect(i)}
         <button
           class="tessera-matching-item left"
           class:selected={isSelected}
@@ -203,8 +170,8 @@
           class:correct={correctMatch}
           class:incorrect={wrongMatch}
           style={color ? `border-color: ${color}; --match-color: ${color}` : ''}
-          onclick={() => matched && !isDisabled ? removeMatch(i) : handleLeftClick(i)}
-          disabled={isDisabled}
+          onclick={() => matched && !q.locked ? removeMatch(i) : handleLeftClick(i)}
+          disabled={q.locked}
           aria-label="{pair.left}{matched ? ' (matched, activate to unmatch)' : ''}"
         >
           {#if matched}
@@ -213,7 +180,7 @@
             </span>
           {/if}
           <span>{pair.left}</span>
-          {#if matched && !isDisabled}
+          {#if matched && !q.locked}
             <span class="tessera-matching-unmatch" aria-hidden="true">×</span>
           {/if}
         </button>
@@ -233,7 +200,7 @@
           class:matched
           style={color ? `border-color: ${color}; --match-color: ${color}` : ''}
           onclick={() => handleRightClick(item.originalIndex)}
-          disabled={isDisabled}
+          disabled={q.locked}
           aria-label="{item.text}{matched ? ' (matched)' : ''}"
         >
           {#if matched}
@@ -248,7 +215,7 @@
     </div>
   </div>
 
-  {#if showFeedback}
+  {#if q.feedbackVisible}
     {@const isCorrect = checkAnswer(matches)}
     <div class="tessera-matching-review">
       {#if isCorrect}
@@ -274,14 +241,14 @@
           <p class="tessera-matching-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}
 {/snippet}
 
-{#if standalone}
+{#if !inQuiz}
   <div class="tessera-matching" aria-label={question}>
     {@render matchingContent()}
   </div>
@@ -289,7 +256,7 @@
 
 {#snippet renderQuestion()}
   <div class="tessera-matching" aria-label={question}>
-    {#if isLocked}
+    {#if q.isLockedCorrect}
       <LockedBanner />
     {/if}
     {@render matchingContent()}

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}