@pie-element/mc-populated-blank 0.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@pie-element/mc-populated-blank",
+  "version": "0.1.0",
+  "description": "Multiple-choice option populates an inline blank in a sentence template (Svelte 5 PIE element)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./delivery": {
+      "development": "./src/delivery/index.ts",
+      "types": "./dist/delivery/index.d.ts",
+      "default": "./dist/delivery/index.js"
+    },
+    "./controller": {
+      "development": "./src/controller/index.ts",
+      "types": "./dist/controller/index.d.ts",
+      "default": "./dist/controller/index.js"
+    },
+    "./author": {
+      "development": "./src/author/index.ts",
+      "types": "./dist/author/index.d.ts",
+      "default": "./dist/author/index.js"
+    },
+    "./print": {
+      "development": "./src/print/index.ts",
+      "types": "./dist/print/index.d.ts",
+      "default": "./dist/print/index.js"
+    },
+    "./iife": {
+      "default": "./dist/index.iife.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "vite build && vite build --config vite.delivery.config.ts && vite build --config vite.controller.config.ts && vite build --config vite.author.config.ts && vite build --config vite.print.config.ts && vite build --config vite.config.iife.ts && tsc --emitDeclarationOnly",
+    "dev": "vite",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "dependencies": {
+    "lodash-es": "^4.17.21"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^7.0.0",
+    "@types/lodash-es": "^4.17.12",
+    "svelte": "^5.54.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.1"
+  }
+}

package/src/author/Author.svelte

@@ -0,0 +1,41 @@
+<svelte:options
+  customElement={{
+    shadow: 'none',
+    props: {
+      model: { type: 'Object' },
+    },
+  }}
+/>
+
+<script lang="ts">
+// Keep the same prop shape expected by the wrapper.
+let { model = $bindable(), onChange }: { model?: any; onChange?: (model: any) => void } = $props();
+</script>
+
+<div class="mc-populated-blank-author-placeholder" role="status" aria-live="polite">
+  <p class="title">Author view placeholder</p>
+  <p class="body">This authoring interface is a placeholder and will be implemented later.</p>
+</div>
+
+<style>
+  .mc-populated-blank-author-placeholder {
+    max-width: 56rem;
+    margin: 24px auto;
+    padding: 20px;
+    border: 1px dashed #cbd5e1;
+    border-radius: 8px;
+    background: #f8fafc;
+    color: #334155;
+  }
+
+  .title {
+    margin: 0 0 8px;
+    font-size: 1rem;
+    font-weight: 600;
+  }
+
+  .body {
+    margin: 0;
+    font-size: 0.9rem;
+  }
+</style>

package/src/author/index.ts

@@ -0,0 +1,28 @@
+import AuthorComponent from './Author.svelte';
+
+const SvelteElementClass = (AuthorComponent as any).element;
+
+class McPopulatedBlankAuthor extends SvelteElementClass {
+  private _model: any = null;
+  private _onChange: ((model: any) => void) | null = null;
+
+  set model(m: any) {
+    this._model = m;
+    super.model = m;
+  }
+
+  get model() {
+    return this._model;
+  }
+
+  set onChange(fn: (model: any) => void) {
+    this._onChange = fn;
+    (this as any).onChange = fn;
+  }
+
+  get onChange() {
+    return this._onChange || (() => {});
+  }
+}
+
+export default McPopulatedBlankAuthor;

package/src/controller/defaults.ts

@@ -0,0 +1,38 @@
+/** Token authors must include exactly once in `template` (HTML). */
+export const BLANK_TOKEN = '{{blank}}';
+
+export default {
+  model: {
+    id: '1',
+    element: 'mc-populated-blank',
+    prompt: '<p><strong>Demo prompt</strong></p>',
+    promptEnabled: true,
+    interactionMode: 'populate_blank' as const,
+    layoutProfile: '',
+    choiceLayout: '',
+    sentenceHtml: '',
+    template: `<p>The answer is ${BLANK_TOKEN}.</p>`,
+    choiceMode: 'text' as const,
+    choices: [
+      { id: 'c1', labelHtml: '<p>Option A</p>' },
+      { id: 'c2', labelHtml: '<p>Option B</p>' },
+      { id: 'c3', labelHtml: '<p>Option C</p>' },
+    ],
+    correctChoiceId: 'c2',
+    hasAudio: false,
+    autoplayAudioEnabled: false,
+    completeAudioEnabled: false,
+    audioUrl: '',
+    audioTranscript: '',
+    showVisibleTranscript: false,
+    locale: '',
+    teacherInstructions: '',
+    teacherInstructionsEnabled: false,
+  },
+  configuration: {
+    prompt: {
+      label: 'Prompt',
+      settings: true,
+    },
+  },
+};

package/src/controller/index.ts

@@ -0,0 +1,273 @@
+import { isEmpty } from 'lodash-es';
+import defaults, { BLANK_TOKEN } from './defaults';
+
+export function countBlankTokens(template: string): number {
+  if (!template) return 0;
+  const re = /\{\{blank\}\}/g;
+  return (template.match(re) || []).length;
+}
+
+export const getCorrectness = (question: any, session: any) => {
+  if (!session || !session.choiceId) {
+    return 'unanswered';
+  }
+  const correct = question?.correctChoiceId || '';
+  if (session.choiceId === correct) {
+    return 'correct';
+  }
+  return 'incorrect';
+};
+
+export const getPartialScore = (_question: any, session: any) => {
+  if (!session || isEmpty(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) =>
+  new Promise((resolve) => {
+    if (!session || isEmpty(session)) {
+      resolve({
+        score: 0,
+        empty: true,
+        traceLog: ['Student did not select any answers. Score is 0.'],
+      });
+      return;
+    }
+
+    session = normalizeSession(session);
+    const correctness = getCorrectness(question, session);
+
+    if (correctness === 'unanswered') {
+      resolve({
+        score: 0,
+        empty: true,
+        traceLog: ['Student did not select any answers. Score is 0.'],
+      });
+      return;
+    }
+
+    const score = correctness === 'correct' ? 1 : 0;
+    const traceLog = [
+      `Mode: ${env?.mode || 'unknown'}.`,
+      `Student selected choice: ${session.choiceId}.`,
+      `Correct choice: ${question?.correctChoiceId || 'none'}.`,
+      `Final score: ${score}.`,
+    ];
+    resolve({ score, empty: false, traceLog });
+  });
+
+export const createDefaultModel = (model: any = {}) => ({ ...defaults.model, ...model });
+
+export const normalizeSession = (s: any) => ({ ...s });
+
+const shouldShuffleChoices = (question: any) => !!question?.shuffle;
+
+const shouldLockChoices = (question: any, env: any) => {
+  if (question?.lockChoiceOrder) return true;
+  if (env?.['@pie-element']?.lockChoiceOrder) return true;
+  return env?.role === 'instructor';
+};
+
+const shuffleArray = <T>(items: T[]): T[] => {
+  const out = [...items];
+  for (let i = out.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [out[i], out[j]] = [out[j], out[i]];
+  }
+  return out;
+};
+
+const getStoredShuffle = (session: any): string[] =>
+  Array.isArray(session?.data?.shuffledValues)
+    ? session.data.shuffledValues
+    : Array.isArray(session?.shuffledValues)
+      ? session.shuffledValues
+      : [];
+
+const applyShuffledValues = (choices: any[], shuffledValues: string[], choiceKey: string) => {
+  const orderedChoices = shuffledValues
+    .map((value) => choices.find((choice) => choice?.[choiceKey] === value))
+    .filter(Boolean);
+
+  if (orderedChoices.length === choices.length) {
+    return orderedChoices;
+  }
+
+  const orderedValues = new Set(orderedChoices.map((choice: any) => 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) => {
+  const choices = Array.isArray(question?.choices) ? [...question.choices] : [];
+  if (!choices.length || !shouldShuffleChoices(question)) {
+    return choices;
+  }
+
+  if (shouldLockChoices(question, env || {})) {
+    return choices;
+  }
+
+  const shuffledValues = getStoredShuffle(session);
+  if (shuffledValues.length) {
+    return applyShuffledValues(choices, shuffledValues, 'id');
+  }
+
+  const shuffledChoices = shuffleArray(choices);
+
+  if (updateSession && typeof updateSession === 'function' && session?.id && session?.element) {
+    const shuffledIds = shuffledChoices.map((choice) => choice?.id).filter(Boolean);
+    if (shuffledIds.length) {
+      await updateSession(session.id, session.element, { shuffledValues: shuffledIds });
+    }
+  }
+
+  return shuffledChoices;
+};
+
+export const model = async (question: any, session: any, env: any, updateSession?: any) => {
+  session = session || {};
+  const normalizedQuestion = createDefaultModel(question);
+  const choices = await getOrderedChoices(normalizedQuestion, session, env, updateSession);
+
+  const out: any = {
+    prompt: normalizedQuestion.promptEnabled ? normalizedQuestion.prompt : null,
+    interactionMode: normalizedQuestion.interactionMode || 'populate_blank',
+    layoutProfile: normalizedQuestion.layoutProfile || '',
+    choiceLayout: normalizedQuestion.choiceLayout || '',
+    sentenceHtml: normalizedQuestion.sentenceHtml || null,
+    template: normalizedQuestion.template,
+    choiceMode: normalizedQuestion.choiceMode,
+    choices,
+    hasAudio: normalizedQuestion.hasAudio,
+    autoplayAudioEnabled: !!normalizedQuestion.autoplayAudioEnabled,
+    completeAudioEnabled: !!normalizedQuestion.completeAudioEnabled,
+    audioUrl: normalizedQuestion.hasAudio ? normalizedQuestion.audioUrl : null,
+    audioTranscript: normalizedQuestion.hasAudio ? normalizedQuestion.audioTranscript : null,
+    showVisibleTranscript: !!normalizedQuestion.showVisibleTranscript,
+    locale: normalizedQuestion.locale || '',
+    disabled: env.mode !== 'gather',
+    view: env.mode === 'view',
+    mode: env.mode,
+  };
+
+  if (env.mode === 'evaluate') {
+    const correctness = getCorrectness(normalizedQuestion, session);
+    out.correctness = correctness;
+    out.responseCorrect = correctness === 'correct';
+    out.correctChoiceId = normalizedQuestion.correctChoiceId;
+  }
+
+  if (env.role === 'instructor' && (env.mode === 'view' || env.mode === 'evaluate')) {
+    out.teacherInstructions = normalizedQuestion.teacherInstructionsEnabled
+      ? normalizedQuestion.teacherInstructions
+      : null;
+  } else {
+    out.teacherInstructions = null;
+  }
+
+  return out;
+};
+
+export const createCorrectResponseSession = (question: any, env: any) => {
+  return new Promise((resolve) => {
+    if (env.mode !== 'evaluate' && env.role === 'instructor') {
+      resolve({
+        id: '1',
+        element: 'mc-populated-blank',
+        choiceId: question?.correctChoiceId || '',
+      });
+    } else {
+      resolve(null);
+    }
+  });
+};
+
+export const validate = (model: any = {}, _config: any = {}) => {
+  const errors: any = {};
+
+  if (model.promptEnabled) {
+    const p = model.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 n = countBlankTokens(template);
+  if (interactionMode === 'audio_mc_only') {
+    if (n > 0) {
+      errors.template = `Template cannot contain ${BLANK_TOKEN} in audio-only mode`;
+    }
+  } else if (interactionMode === 'populate_blank') {
+    if (n === 0) {
+      errors.template = `Template must contain exactly one ${BLANK_TOKEN} placeholder`;
+    } else if (n > 1) {
+      errors.template = `Template must contain only one ${BLANK_TOKEN} placeholder`;
+    }
+  } else {
+    errors.interactionMode = 'Unknown interaction mode';
+  }
+
+  const choices = Array.isArray(model.choices) ? model.choices : [];
+  if (choices.length < 2) {
+    errors.choices = 'At least two choices are required';
+  }
+
+  const mode = model.choiceMode || 'text';
+  for (let i = 0; i < choices.length; i++) {
+    const c = choices[i];
+    if (!c?.id) {
+      errors.choices = `Choice ${i + 1} is missing an id`;
+      break;
+    }
+    if (mode === 'text') {
+      const lbl = (c.labelHtml || '').trim();
+      if (!lbl || lbl === '<p></p>') {
+        errors.choices = `Choice ${i + 1} needs label text`;
+        break;
+      }
+    } else {
+      if (!c.imageUrl?.trim()) {
+        errors.choices = `Choice ${i + 1} needs an image URL`;
+        break;
+      }
+      if (!c.imageAlt?.trim()) {
+        errors.choices = `Choice ${i + 1} needs image alt text`;
+        break;
+      }
+    }
+  }
+
+  const correct = model.correctChoiceId;
+  if (!correct || !choices.some((c: any) => c.id === correct)) {
+    errors.correctChoiceId = 'Correct choice must match one of the choice ids';
+  }
+
+  if (model.hasAudio) {
+    const hasAudioUrl = !!model.audioUrl?.trim();
+    const hasTranscript = !!model.audioTranscript?.trim();
+    if (!hasAudioUrl && !hasTranscript) {
+      errors.audioTranscript = 'Audio transcript or audio URL is required when audio is enabled';
+    }
+  }
+
+  return errors;
+};