@pie-element/mc-populated-blank 0.2.10 → 0.2.11

package/src/controller/index.ts

@@ -1,4 +1,11 @@
 import defaults, { BLANK_TOKEN, DEFAULT_LAYOUT_LIMITS } from './defaults';
+import type {
+  McpbChoice,
+  McpbQuestion,
+  McpbSession,
+  McpbEnv,
+  McpbCorrectness,
+} from '../shared/types';
 
 const isEmptyObject = (value: unknown): boolean =>
   !!value &&
@@ -12,8 +19,8 @@ export function countBlankTokens(template: string): number {
   return (template.match(re) || []).length;
 }
 
-export const getCorrectness = (question: any, session: any) => {
-  if (!session || !session.choiceId) {
+export const getCorrectness = (question: McpbQuestion, session: McpbSession): McpbCorrectness => {
+  if (!session?.choiceId) {
     return 'unanswered';
   }
   const correct = question?.correctChoiceId || '';
@@ -23,28 +30,14 @@ export const getCorrectness = (question: any, session: any) => {
   return 'incorrect';
 };
 
-export const getPartialScore = (_question: any, session: any) => {
+export const getPartialScore = (_question: McpbQuestion, session: McpbSession) => {
   if (!session || isEmptyObject(session) || !session.choiceId) {
     return 0;
   }
   return 1;
 };
 
-export const isComplete = (question: any, session: any, audioComplete = false) => {
-  if (!session || !session.choiceId) {
-    return false;
-  }
-  const autoplayAudioEnabled = !!question?.autoplayAudioEnabled;
-  const completeAudioEnabled = !!question?.completeAudioEnabled;
-  const requiresAudioCompletion =
-    autoplayAudioEnabled && completeAudioEnabled && !!question?.hasAudio;
-  if (requiresAudioCompletion && !audioComplete) {
-    return false;
-  }
-  return true;
-};
-
-export const outcome = (question: any, session: any, env: any) =>
+export const outcome = (question: McpbQuestion, session: McpbSession, env: McpbEnv) =>
   new Promise((resolve) => {
     if (!session || isEmptyObject(session)) {
       resolve({
@@ -77,7 +70,7 @@ export const outcome = (question: any, session: any, env: any) =>
     resolve({ score, empty: false, traceLog });
   });
 
-export const createDefaultModel = (model: any = {}) => ({
+export const createDefaultModel = (model: McpbQuestion = {}) => ({
   ...defaults.model,
   ...model,
   layoutLimits: {
@@ -86,13 +79,13 @@ export const createDefaultModel = (model: any = {}) => ({
   },
 });
 
-export const normalize = (question: any = {}) => createDefaultModel(question);
+export const normalize = (question: McpbQuestion = {}) => createDefaultModel(question);
 
-export const normalizeSession = (s: any) => ({ ...s });
+export const normalizeSession = (s: McpbSession): McpbSession => ({ ...s });
 
-const shouldShuffleChoices = (question: any) => !!question?.shuffle;
+const shouldShuffleChoices = (question: McpbQuestion) => !!question?.shuffle;
 
-const shouldLockChoices = (question: any, env: any) => {
+const shouldLockChoices = (question: McpbQuestion, env: McpbEnv) => {
   if (question?.lockChoiceOrder) return true;
   if (env?.['@pie-element']?.lockChoiceOrder) return true;
   return env?.role === 'instructor';
@@ -107,28 +100,43 @@ function shuffleArray<T>(items: T[]): T[] {
   return out;
 }
 
-const getStoredShuffle = (session: any): string[] =>
+const getStoredShuffle = (session: McpbSession): string[] =>
   Array.isArray(session?.data?.shuffledValues)
     ? session.data.shuffledValues
     : Array.isArray(session?.shuffledValues)
       ? session.shuffledValues
       : [];
 
-const applyShuffledValues = (choices: any[], shuffledValues: string[], choiceKey: string) => {
+const applyShuffledValues = (
+  choices: McpbChoice[],
+  shuffledValues: string[],
+  choiceKey: keyof McpbChoice
+) => {
   const orderedChoices = shuffledValues
     .map((value) => choices.find((choice) => choice?.[choiceKey] === value))
-    .filter(Boolean);
+    .filter((c): c is McpbChoice => !!c);
 
   if (orderedChoices.length === choices.length) {
     return orderedChoices;
   }
 
-  const orderedValues = new Set(orderedChoices.map((choice: any) => choice[choiceKey]));
+  const orderedValues = new Set(orderedChoices.map((choice) => choice[choiceKey]));
   const leftovers = choices.filter((choice) => !orderedValues.has(choice?.[choiceKey]));
   return [...orderedChoices, ...leftovers];
 };
 
-const getOrderedChoices = async (question: any, session: any, env: any, updateSession?: any) => {
+type UpdateSessionFn = (
+  id: string,
+  element: string,
+  data: { shuffledValues: string[] }
+) => Promise<void>;
+
+const getOrderedChoices = async (
+  question: McpbQuestion,
+  session: McpbSession,
+  env: McpbEnv,
+  updateSession?: UpdateSessionFn
+) => {
   const choices = Array.isArray(question?.choices) ? [...question.choices] : [];
   if (!choices.length || !shouldShuffleChoices(question)) {
     return choices;
@@ -155,13 +163,18 @@ const getOrderedChoices = async (question: any, session: any, env: any, updateSe
   return shuffledChoices;
 };
 
-export const model = async (question: any, session: any, env: any, updateSession?: any) => {
-  session = session || {};
-  const safeEnv = env || {};
+export const model = async (
+  question: McpbQuestion,
+  session: McpbSession | null,
+  env: McpbEnv | null,
+  updateSession?: UpdateSessionFn
+) => {
+  const safeSession: McpbSession = session || {};
+  const safeEnv: McpbEnv = env || {};
   const normalizedQuestion = normalize(question);
-  const choices = await getOrderedChoices(normalizedQuestion, session, safeEnv, updateSession);
+  const choices = await getOrderedChoices(normalizedQuestion, safeSession, safeEnv, updateSession);
 
-  const out: any = {
+  const out: Record<string, unknown> = {
     prompt: normalizedQuestion.promptEnabled ? normalizedQuestion.prompt : null,
     interactionMode: normalizedQuestion.interactionMode || 'populate_blank',
     layoutProfile: normalizedQuestion.layoutProfile || '',
@@ -206,7 +219,7 @@ export const model = async (question: any, session: any, env: any, updateSession
   };
 
   if (safeEnv.mode === 'evaluate') {
-    const correctness = getCorrectness(normalizedQuestion, session);
+    const correctness = getCorrectness(normalizedQuestion, safeSession);
     out.correctness = correctness;
     out.responseCorrect = correctness === 'correct';
     out.correctChoiceId = normalizedQuestion.correctChoiceId;
@@ -223,7 +236,7 @@ export const model = async (question: any, session: any, env: any, updateSession
   return out;
 };
 
-export const createCorrectResponseSession = (question: any, env: any) => {
+export const createCorrectResponseSession = (question: McpbQuestion, env: McpbEnv) => {
   return new Promise((resolve) => {
     if (env.mode !== 'evaluate' && env.role === 'instructor') {
       resolve({
@@ -237,18 +250,18 @@ export const createCorrectResponseSession = (question: any, env: any) => {
   });
 };
 
-export const validate = (model: any = {}, _config: any = {}) => {
-  const errors: any = {};
+export const validate = (question: McpbQuestion = {}, _config: Record<string, unknown> = {}) => {
+  const errors: Record<string, string> = {};
 
-  if (model.promptEnabled) {
-    const p = model.prompt?.trim() || '';
+  if (question.promptEnabled) {
+    const p = question.prompt?.trim() || '';
     if (!p || p === '<p></p>') {
       errors.prompt = 'Prompt is required when prompt is enabled';
     }
   }
 
-  const interactionMode = model.interactionMode || 'populate_blank';
-  const template = model.template || '';
+  const interactionMode = question.interactionMode || 'populate_blank';
+  const template = question.template || '';
   const n = countBlankTokens(template);
   if (interactionMode === 'audio_mc_only') {
     if (n > 0) {
@@ -264,12 +277,12 @@ export const validate = (model: any = {}, _config: any = {}) => {
     errors.interactionMode = 'Unknown interaction mode';
   }
 
-  const choices = Array.isArray(model.choices) ? model.choices : [];
+  const choices = Array.isArray(question.choices) ? question.choices : [];
   if (choices.length < 2) {
     errors.choices = 'At least two choices are required';
   }
 
-  const mode = model.choiceMode || 'text';
+  const mode = question.choiceMode || 'text';
   for (let i = 0; i < choices.length; i++) {
     const c = choices[i];
     if (!c?.id) {
@@ -294,19 +307,19 @@ export const validate = (model: any = {}, _config: any = {}) => {
     }
   }
 
-  const correct = model.correctChoiceId;
-  if (!correct || !choices.some((c: any) => c.id === correct)) {
+  const correct = question.correctChoiceId;
+  if (!correct || !choices.some((c) => c.id === correct)) {
     errors.correctChoiceId = 'Correct choice must match one of the choice ids';
   }
 
-  if (model.hasAudio) {
-    const hasAudioUrl = !!model.audioUrl?.trim();
+  if (question.hasAudio) {
+    const hasAudioUrl = !!question.audioUrl?.trim();
     if (!hasAudioUrl) {
       errors.audioUrl = 'A playable audio URL is required when audio is enabled';
     }
   }
 
-  const limits = model?.layoutLimits;
+  const limits = question?.layoutLimits;
   if (limits && typeof limits === 'object') {
     const numericLimitKeys = [
       'blankStandaloneWidthRem',
@@ -344,9 +357,9 @@ export const validate = (model: any = {}, _config: any = {}) => {
       'inlineGridRowGapRem',
       'inlineTemplateMarginTopRem',
       'inlineChoicesMarginTopRem',
-    ];
+    ] as const;
     for (const key of numericLimitKeys) {
-      if (limits[key] === undefined || limits[key] === null || limits[key] === '') continue;
+      if (limits[key] === undefined || limits[key] === null) continue;
       const value = Number(limits[key]);
       if (!Number.isFinite(value) || value <= 0) {
         errors.layoutLimits = `${key} must be a positive number when provided`;

package/src/delivery/AudioPlayer.svelte

@@ -0,0 +1,246 @@
+<script lang="ts">
+import { computeAudioMode } from './computeAudioMode';
+
+interface AudioButtonSkin {
+  silentUrl: string;
+  playingUrl: string;
+}
+
+interface UiText {
+  clickToEnableAutoplay: string;
+  transcriptLabel: string;
+  audioResourceUnavailable: string;
+  listenSilentAlt?: string;
+  listenPlayingAlt?: string;
+  listenSilentAltEs?: string;
+  listenPlayingAltEs?: string;
+}
+
+const AUDIO_PLAYBACK = {
+  IDLE: 'idle',
+  PLAYING: 'playing',
+  BLOCKED: 'blocked',
+  PAUSED: 'paused',
+} as const;
+type AudioPlaybackState = (typeof AUDIO_PLAYBACK)[keyof typeof AUDIO_PLAYBACK];
+
+let {
+  hasAudio = false,
+  audioUrl,
+  useFeatureButtonAudio = false,
+  autoplayEnabled = false,
+  audioTranscript,
+  showVisibleTranscript,
+  transcriptId,
+  featureAudioSkin,
+  uiText,
+  locale = '',
+  onaudiostarted,
+  onaudioended,
+}: {
+  hasAudio?: boolean;
+  audioUrl?: string;
+  useFeatureButtonAudio?: boolean;
+  autoplayEnabled?: boolean;
+  audioTranscript?: string;
+  showVisibleTranscript: boolean;
+  transcriptId: string;
+  featureAudioSkin: AudioButtonSkin;
+  uiText: UiText;
+  locale?: string;
+  onaudiostarted?: () => void;
+  onaudioended?: () => void;
+} = $props();
+
+let audioEl = $state<HTMLAudioElement | null>(null);
+let featureAudioButtonEl = $state<HTMLButtonElement | null>(null);
+let autoplayEnableButtonEl = $state<HTMLButtonElement | null>(null);
+let audioPlaybackState = $state<AudioPlaybackState>(AUDIO_PLAYBACK.IDLE);
+
+const audioMode = $derived(computeAudioMode({ hasAudio, audioUrl, useFeatureButtonAudio }));
+const isMediaPlaying = $derived(audioPlaybackState === AUDIO_PLAYBACK.PLAYING);
+const autoPlayPromptOpen = $derived(audioPlaybackState === AUDIO_PLAYBACK.BLOCKED);
+const audioErrorMessage = $derived(audioMode === 'error' ? uiText.audioResourceUnavailable : '');
+
+// Reset playback state when audioUrl changes so autoplay re-fires for a new question.
+$effect(() => {
+  audioUrl;
+  audioPlaybackState = AUDIO_PLAYBACK.IDLE;
+});
+
+function playFeatureAudio() {
+  if (audioMode !== 'none' && audioMode !== 'error' && audioEl) {
+    audioEl.play().catch(() => {});
+  }
+}
+
+function handleEnableAutoplayClick() {
+  if (audioMode !== 'none' && audioMode !== 'error' && audioEl) {
+    audioEl.play().finally(() => {
+      if (audioPlaybackState === AUDIO_PLAYBACK.BLOCKED) audioPlaybackState = AUDIO_PLAYBACK.PAUSED;
+    });
+  }
+}
+
+function useListener<K extends keyof HTMLElementEventMap>(
+  getEl: () => EventTarget | null | undefined,
+  event: K,
+  handler: (e: HTMLElementEventMap[K]) => void
+) {
+  $effect(() => {
+    const el = getEl();
+    if (!el) return;
+    el.addEventListener(event, handler as EventListener);
+    return () => el.removeEventListener(event, handler as EventListener);
+  });
+}
+
+useListener(
+  () => audioEl,
+  'playing',
+  () => {
+    audioPlaybackState = AUDIO_PLAYBACK.PLAYING;
+    onaudiostarted?.();
+  }
+);
+
+useListener(
+  () => audioEl,
+  'ended',
+  () => {
+    audioPlaybackState = AUDIO_PLAYBACK.PAUSED;
+    onaudioended?.();
+  }
+);
+
+useListener(
+  () => featureAudioButtonEl,
+  'click',
+  () => playFeatureAudio()
+);
+useListener(
+  () => autoplayEnableButtonEl,
+  'click',
+  () => handleEnableAutoplayClick()
+);
+
+$effect(() => {
+  if (!autoplayEnabled || audioMode === 'none' || audioMode === 'error') return;
+  if (audioPlaybackState !== AUDIO_PLAYBACK.IDLE) return;
+  if (audioEl && audioUrl) {
+    audioPlaybackState = AUDIO_PLAYBACK.PAUSED;
+    audioEl.play().catch(() => {
+      audioPlaybackState = AUDIO_PLAYBACK.BLOCKED;
+    });
+  }
+});
+
+function speechButtonLabel(loc = '') {
+  return loc.toLowerCase().startsWith('es') ? 'Escuchar' : 'Listen';
+}
+
+function silentAlt(loc = '') {
+  return loc.toLowerCase().startsWith('es')
+    ? (uiText.listenSilentAltEs ?? 'Escuchar. Repetir las instrucciones.')
+    : (uiText.listenSilentAlt ?? 'Repeat instructions');
+}
+
+function playingAlt(loc = '') {
+  return loc.toLowerCase().startsWith('es')
+    ? (uiText.listenPlayingAltEs ?? 'Escuchar. Estas son las instrucciones.')
+    : (uiText.listenPlayingAlt ?? 'Instructions are playing');
+}
+</script>
+
+{#if audioMode !== 'none'}
+  <div class="mb-4 audio-container pie-audio-container">
+    {#if audioMode === 'feature-button'}
+      <audio
+        bind:this={audioEl}
+        class="sr-only pie-audio-player"
+        preload="metadata"
+        src={audioUrl}
+        aria-hidden="true"
+        tabindex="-1"
+      ></audio>
+      <button
+        bind:this={featureAudioButtonEl}
+        class="listen-button pie-listen-button rli-feature-audio"
+        type="button"
+        aria-label={speechButtonLabel(locale)}
+      >
+        <img
+          class={`listen-feature-icon pie-listen-icon rli-feature-listen ${isMediaPlaying ? '' : 'listen-active'}`}
+          src={featureAudioSkin.silentUrl}
+          alt={silentAlt(locale)}
+        />
+        <img
+          class={`listen-feature-icon pie-listen-icon rli-feature-listen ${isMediaPlaying ? 'listen-active' : ''}`}
+          src={featureAudioSkin.playingUrl}
+          alt={playingAlt(locale)}
+        />
+      </button>
+    {:else if audioMode === 'controls'}
+      <audio
+        bind:this={audioEl}
+        controls
+        class="w-full max-w-md pie-audio-player"
+        preload="metadata"
+        src={audioUrl}
+        aria-describedby={audioTranscript ? transcriptId : undefined}
+      >
+        <track kind="captions" />
+      </audio>
+      {#if autoPlayPromptOpen}
+        <button
+          bind:this={autoplayEnableButtonEl}
+          class="mt-2 text-sm underline pie-audio-autoplay-enable"
+          type="button"
+        >
+          {uiText.clickToEnableAutoplay}
+        </button>
+      {/if}
+    {:else if audioMode === 'error'}
+      <p class="text-sm text-red-700 pie-audio-error" role="alert">{audioErrorMessage}</p>
+    {/if}
+  </div>
+{/if}
+
+<style>
+  .listen-button {
+    width: var(--mpb-listen-button-size, 128px);
+    height: var(--mpb-listen-button-size, 128px);
+    border: 0;
+    padding: 0;
+    background-color: transparent;
+    cursor: pointer;
+    z-index: 1;
+  }
+
+  .listen-button:hover {
+    background-color: #e2f1fe;
+  }
+
+  .listen-feature-icon {
+    width: var(--mpb-listen-button-size, 128px);
+    height: var(--mpb-listen-button-size, 128px);
+    object-fit: contain;
+    display: none;
+  }
+
+  .listen-feature-icon.listen-active {
+    display: block;
+  }
+
+  .sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+</style>

package/src/delivery/AudioPlayer.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { mount, unmount, flushSync } from 'svelte';
+import AudioPlayer from './AudioPlayer.svelte';
+
+const BASE_PROPS = {
+  hasAudio: true,
+  audioUrl: 'https://example.com/audio.mp3',
+  useFeatureButtonAudio: false,
+  autoplayEnabled: false,
+  audioTranscript: 'The word is look.',
+  showVisibleTranscript: false,
+  transcriptId: 'test-transcript',
+  featureAudioSkin: { silentUrl: '', playingUrl: '' },
+  uiText: {
+    clickToEnableAutoplay: 'Click to enable',
+    transcriptLabel: 'Transcript',
+    audioResourceUnavailable: 'Unavailable',
+    listenSilentAlt: 'Repeat instructions',
+    listenPlayingAlt: 'Instructions are playing',
+    listenSilentAltEs: 'Escuchar. Repetir las instrucciones.',
+    listenPlayingAltEs: 'Escuchar. Estas son las instrucciones.',
+  },
+};
+
+function mountPlayer(props: Partial<typeof BASE_PROPS>) {
+  const target = document.createElement('div');
+  document.body.appendChild(target);
+  const component = mount(AudioPlayer, { target, props: { ...BASE_PROPS, ...props } });
+  return { target, component };
+}
+
+const mounts: Array<{ target: HTMLElement; component: ReturnType<typeof mount> }> = [];
+
+afterEach(() => {
+  for (const { target, component } of mounts.splice(0)) {
+    unmount(component);
+    target.remove();
+  }
+});
+
+describe('AudioPlayer — audio element', () => {
+  it('renders native controls when hasAudio=true and useFeatureButtonAudio=false', () => {
+    const { target, component } = mountPlayer({ useFeatureButtonAudio: false });
+    mounts.push({ target, component });
+    flushSync();
+    expect(target.querySelector('.pie-audio-player')).not.toBeNull();
+  });
+
+  it('renders nothing when hasAudio is false', () => {
+    const { target, component } = mountPlayer({ hasAudio: false });
+    mounts.push({ target, component });
+    flushSync();
+    expect(target.querySelector('.pie-audio-container')).toBeNull();
+  });
+
+  it('renders an error message when hasAudio=true but audioUrl is missing', () => {
+    const { target, component } = mountPlayer({ audioUrl: undefined });
+    mounts.push({ target, component });
+    flushSync();
+    expect(target.querySelector('.pie-audio-error')).not.toBeNull();
+  });
+
+  it('renders the feature button when useFeatureButtonAudio=true', () => {
+    const { target, component } = mountPlayer({ useFeatureButtonAudio: true });
+    mounts.push({ target, component });
+    flushSync();
+    expect(target.querySelector('.pie-listen-button')).not.toBeNull();
+  });
+
+  it('silent image alt is "Repeat instructions" in feature-button mode', () => {
+    const { target, component } = mountPlayer({ useFeatureButtonAudio: true });
+    mounts.push({ target, component });
+    flushSync();
+    const imgs = target.querySelectorAll('.pie-listen-icon');
+    const alts = Array.from(imgs).map((el) => (el as HTMLImageElement).alt);
+    expect(alts).toContain('Repeat instructions');
+  });
+
+  it('playing image alt is "Instructions are playing" in feature-button mode', () => {
+    const { target, component } = mountPlayer({ useFeatureButtonAudio: true });
+    mounts.push({ target, component });
+    flushSync();
+    const imgs = target.querySelectorAll('.pie-listen-icon');
+    const alts = Array.from(imgs).map((el) => (el as HTMLImageElement).alt);
+    expect(alts).toContain('Instructions are playing');
+  });
+});
+
+describe('AudioPlayer — autoplay-blocked prompt', () => {
+  it('shows pie-audio-autoplay-enable when autoplay is blocked by the browser', async () => {
+    // Override HTMLAudioElement.play on the global so all audio elements reject
+    const originalPlay = HTMLMediaElement.prototype.play;
+    HTMLMediaElement.prototype.play = () =>
+      Promise.reject(new DOMException('autoplay blocked', 'NotAllowedError'));
+
+    const { target, component } = mountPlayer({
+      useFeatureButtonAudio: false,
+      autoplayEnabled: true,
+    });
+    mounts.push({ target, component });
+    flushSync();
+
+    // Allow the rejected promise microtask to settle
+    await Promise.resolve();
+    flushSync();
+
+    expect(target.querySelector('.pie-audio-autoplay-enable')).not.toBeNull();
+
+    HTMLMediaElement.prototype.play = originalPlay;
+  });
+
+  it('hides pie-audio-autoplay-enable when autoplay is not blocked', async () => {
+    const originalPlay = HTMLMediaElement.prototype.play;
+    HTMLMediaElement.prototype.play = () => Promise.resolve();
+
+    const { target, component } = mountPlayer({
+      useFeatureButtonAudio: false,
+      autoplayEnabled: true,
+    });
+    mounts.push({ target, component });
+    flushSync();
+    await Promise.resolve();
+    flushSync();
+
+    expect(target.querySelector('.pie-audio-autoplay-enable')).toBeNull();
+
+    HTMLMediaElement.prototype.play = originalPlay;
+  });
+
+  it('pie-audio-autoplay-enable is not rendered in feature-button mode even when autoplay is blocked', async () => {
+    const originalPlay = HTMLMediaElement.prototype.play;
+    HTMLMediaElement.prototype.play = () =>
+      Promise.reject(new DOMException('autoplay blocked', 'NotAllowedError'));
+
+    const { target, component } = mountPlayer({
+      useFeatureButtonAudio: true,
+      autoplayEnabled: true,
+    });
+    mounts.push({ target, component });
+    flushSync();
+    await Promise.resolve();
+    flushSync();
+
+    // Feature-button mode never shows the enable-autoplay prompt
+    expect(target.querySelector('.pie-audio-autoplay-enable')).toBeNull();
+
+    HTMLMediaElement.prototype.play = originalPlay;
+  });
+});