@pie-element/ebsr 0.1.0

package/src/controller/defaults.ts

@@ -0,0 +1,35 @@
+// @ts-nocheck
+/**
+ * @synced-from pie-elements/packages/ebsr/controller/src/defaults.js
+ * @auto-generated
+ *
+ * This file is automatically synced from pie-elements and converted to TypeScript.
+ * Manual edits will be overwritten on next sync.
+ * To make changes, edit the upstream JavaScript file and run sync again.
+ */
+
+const partModel = (base) => ({
+  choiceMode: 'radio',
+  choicePrefix: 'letters',
+  choices: [],
+  choicesLayout: 'vertical',
+  feedbackEnabled: false,
+  gridColumns: 2,
+  prompt: '',
+  promptEnabled: true,
+  rationale: '',
+  rationaleEnabled: true,
+  spellCheckEnabled: true,
+  studentInstructionsEnabled: true,
+  teacherInstructions: '',
+  teacherInstructionsEnabled: true,
+  toolbarEditorPosition: 'bottom',
+  ...base,
+});
+
+export default {
+  partLabels: true,
+  partLabelType: 'Letters',
+  partA: partModel(),
+  partB: partModel(),
+};

package/src/controller/index.ts

@@ -0,0 +1,452 @@
+// @ts-nocheck
+/**
+ * @synced-from pie-elements/packages/ebsr/controller/src/index.js
+ * @auto-generated
+ *
+ * This file is automatically synced from pie-elements and converted to TypeScript.
+ * Manual edits will be overwritten on next sync.
+ * To make changes, edit the upstream JavaScript file and run sync again.
+ */
+
+import defaults from './defaults.js';
+import { lockChoices, getShuffledChoices, partialScoring } from '@pie-element/shared-controller-utils';
+import { isResponseCorrect } from './utils.js';
+import { get, isEmpty } from 'lodash-es';
+import Translator from '@pie-lib/translator';
+
+const { translator } = Translator;
+
+const prepareChoice = (model, env, defaultFeedback) => (choice) => {
+  const out = {
+    label: choice.label,
+    value: choice.value,
+  };
+
+  if (env.role === 'instructor' && (env.mode === 'view' || env.mode === 'evaluate')) {
+    out.rationale = model.rationaleEnabled ? choice.rationale : null;
+  } else {
+    out.rationale = null;
+  }
+
+  if (env.mode === 'evaluate') {
+    out.correct = !!choice.correct;
+
+    if (model.feedbackEnabled) {
+      const feedbackType = (choice.feedback && choice.feedback.type) || 'none';
+
+      if (feedbackType === 'default') {
+        out.feedback = defaultFeedback[choice.correct ? 'correct' : 'incorrect'];
+      } else if (feedbackType === 'custom') {
+        out.feedback = choice.feedback.value;
+      }
+    }
+  }
+
+  return out;
+};
+
+const parsePart = (part, key, session, env) => {
+  const defaultFeedback = Object.assign({ correct: 'Correct', incorrect: 'Incorrect' }, part.defaultFeedback);
+
+  let choices = part.choices ? part.choices.map(prepareChoice(part, env, defaultFeedback)) : [];
+
+  return {
+    ...part,
+    choices,
+    disabled: env.mode !== 'gather',
+    complete: {
+      min: part.choices.filter((c) => c.correct).length,
+    },
+    responseCorrect: env.mode === 'evaluate' ? isResponseCorrect(part, key, session) : undefined,
+  };
+};
+
+const normalizePart = (model, base) => ({
+  ...base,
+  ...model,
+  choicesLayout: model.choicesLayout || (model.verticalMode === false && 'horizontal') || 'vertical',
+});
+
+export const normalize = ({ partA = {}, partB = {}, language, ...question }) => ({
+  ...defaults,
+  ...question,
+  partA: normalizePart(partA, { ...defaults.partA, language }),
+  partB: normalizePart(partB, { ...defaults.partB, language }),
+});
+
+/**
+ *
+ * @param {*} question
+ * @param {*} session
+ * @param {*} env
+ * @param {*} updateSession - optional - a function that will set the properties passed into it on the session.
+ */
+export async function model(question, session, env, updateSession) {
+  const normalizedQuestion = normalize(question);
+  const partA = parsePart(normalizedQuestion.partA, 'partA', session, env);
+  const partB = parsePart(normalizedQuestion.partB, 'partB', session, env);
+
+  const shuffledValues = {};
+
+  const us = (part) => (id, element, update) =>
+    new Promise((resolve) => {
+      shuffledValues[part] = update.shuffledValues;
+      resolve();
+    });
+
+  const partASession = get(session, 'value.partA');
+  const partALockChoiceOrder = lockChoices(normalizedQuestion.partA, partASession, env);
+
+  const { choices: partAChoices } = partA || {};
+  const { choices: partBChoices } = partB || {};
+
+  if (!partALockChoiceOrder && partAChoices && partAChoices.length) {
+    partA.choices = await getShuffledChoices(
+      partAChoices,
+      { shuffledValues: (session.shuffledValues || {}).partA },
+      us('partA'),
+      'value',
+    );
+  }
+
+  const partBSession = get(session, 'value.partB');
+  const partBLockChoiceOrder = lockChoices(normalizedQuestion.partB, partBSession, env);
+
+  if (!partBLockChoiceOrder && partBChoices && partBChoices.length) {
+    partB.choices = await getShuffledChoices(
+      partBChoices,
+      { shuffledValues: (session.shuffledValues || {}).partB },
+      us('partB'),
+      'value',
+    );
+  }
+
+  if (!isEmpty(shuffledValues)) {
+    if (updateSession && typeof updateSession === 'function') {
+      updateSession(session.id, session.element, {
+        shuffledValues,
+      }).catch((e) => {
+        // eslint-disable-next-line no-console
+        console.error('update session failed', e);
+      });
+    }
+  }
+
+  if (normalizedQuestion.partLabels) {
+    const language = normalizedQuestion.language;
+    partA.partLabel = translator.t('ebsr.part', {
+      lng: language,
+      index: normalizedQuestion.partLabelType === 'Letters' ? 'A' : '1',
+    });
+    partB.partLabel = translator.t('ebsr.part', {
+      lng: language,
+      index: normalizedQuestion.partLabelType === 'Letters' ? 'B' : '2',
+    });
+  } else {
+    partA.partLabel = undefined;
+    partB.partLabel = undefined;
+  }
+
+  if (env.role === 'instructor' && (env.mode === 'view' || env.mode === 'evaluate')) {
+    partA.teacherInstructions = normalizedQuestion.partA.teacherInstructionsEnabled
+      ? normalizedQuestion.partA.teacherInstructions
+      : null;
+    partB.teacherInstructions = normalizedQuestion.partB.teacherInstructionsEnabled
+      ? normalizedQuestion.partB.teacherInstructions
+      : null;
+  } else {
+    partA.teacherInstructions = null;
+    partB.teacherInstructions = null;
+  }
+
+  partA.prompt = normalizedQuestion.partA.promptEnabled ? normalizedQuestion.partA.prompt : null;
+  partB.prompt = normalizedQuestion.partB.promptEnabled ? normalizedQuestion.partB.prompt : null;
+
+  return new Promise((resolve) => {
+    resolve({
+      disabled: env.mode !== 'gather',
+      mode: env.mode,
+      extraCSSRules: normalizedQuestion.extraCSSRules,
+      partA,
+      partB,
+    });
+  });
+}
+
+export const createDefaultModel = (model = {}) =>
+  new Promise((resolve) => {
+    resolve({
+      ...defaults,
+      ...model,
+    });
+  });
+
+const isCorrect = (c) => c.correct === true;
+
+const getScore = (config, sessionPart, key, partialScoringEnabled) => {
+  const { choices = [] } = (config && config[key]) || {};
+  const maxScore = choices.length;
+  const { value: sessionPartValue } = sessionPart || {};
+
+  const chosen = (c) => !!(sessionPartValue || []).find((v) => v === c.value);
+  const correctAndNotChosen = (c) => isCorrect(c) && !chosen(c);
+  const incorrectAndChosen = (c) => !isCorrect(c) && chosen(c);
+  const correctChoices = choices.reduce((total, choice) => {
+    if (correctAndNotChosen(choice) || incorrectAndChosen(choice)) {
+      return total - 1;
+    } else {
+      return total;
+    }
+  }, choices.length);
+
+  // determine score for a part
+  if (!partialScoringEnabled && correctChoices < maxScore) {
+    return 0;
+  }
+
+  return parseFloat(maxScore ? (correctChoices / maxScore).toFixed(2) : 0);
+};
+
+/**
+ * Generates detailed trace log for math-templated scoring evaluation
+ * @param {Object} question
+ * @param {Object} session
+ * @param {Object} env
+ * @returns {Array<string>} traceLog
+ */
+export const getLogTrace = (question, session, env) => {
+  const traceLog = [];
+
+  if (!session || !session.value) {
+    traceLog.push('Student did not answer the question.');
+    return traceLog;
+  }
+
+  const { value } = session;
+  const { partA, partB } = value;
+
+  const partialScoringEnabled = partialScoring.enabled(question, env);
+
+  traceLog.push(
+    `Scoring method: ${partialScoringEnabled ? 'partial scoring' : 'all-or-nothing scoring'}.`
+  );
+
+  const partAquestionType =
+    question.partA.choiceMode === 'radio'
+      ? 'multiple-choice (radio)'
+      : 'multiple-select (checkbox)';
+  traceLog.push(`Part A question type: ${partAquestionType}.`);
+
+  const partASelections = partA?.value || [];
+  const partACorrectChoices = (question.partA.choices || []).filter((c) => c.correct);
+  const partACorrectValues = partACorrectChoices.map((c) => c.value);
+  const partACorrectSelected = partASelections.filter((v) => partACorrectValues.includes(v));
+  const partAIncorrectSelected = partASelections.filter((v) => !partACorrectValues.includes(v));
+
+  if (partASelections.length) {
+    traceLog.push(
+      `Part A: student selected ${partASelections.length} choice(s) (${partACorrectSelected.length} correct, ${partAIncorrectSelected.length} incorrect).`
+    );
+  }
+  
+  const scoreA = getScore(question, partA, 'partA', partialScoringEnabled);
+  traceLog.push(`Part A score: ${scoreA}.`);
+
+  const partBquestionType =
+    question.partB.choiceMode === 'radio'
+      ? 'multiple-choice (radio)'
+      : 'multiple-select (checkbox)';
+  traceLog.push(`Part B question type: ${partBquestionType}.`);
+
+  const partBSelections = partB?.value || [];
+  const partBCorrectChoices = (question.partB.choices || []).filter((c) => c.correct);
+  const partBCorrectValues = partBCorrectChoices.map((c) => c.value);
+  const correctSelected = partBSelections.filter((v) => partBCorrectValues.includes(v));
+  const incorrectSelected = partBSelections.filter((v) => !partBCorrectValues.includes(v));
+
+  if (partBSelections.length) {
+    traceLog.push(
+      `Part B: student selected ${partBSelections.length} choice(s) (${correctSelected.length} correct, ${incorrectSelected.length} incorrect).`
+    );
+  }
+
+  const scoreB = getScore(question, partB, 'partB', partialScoringEnabled);
+  traceLog.push(`Part B score: ${scoreB}.`);
+
+  if (!partialScoringEnabled) {
+    traceLog.push(
+      'Final score is awarded only if both Part A and Part B are completely correct.'
+    );
+    traceLog.push(`Final score: ${scoreA === 1 && scoreB === 1 ? 1 : 0}.`);
+  } else {
+    traceLog.push(
+      'With partial scoring enabled, Part A must be correct to earn any credit.'
+    );
+
+    let finalScore = 0;
+    if (scoreA === 1 && scoreB === 1) {
+      finalScore = 2;
+    } else if (scoreA === 1 && scoreB < 1) {
+      finalScore = 1;
+    }
+
+    traceLog.push(`Final score: ${finalScore}.`);
+  }
+
+  return traceLog;
+};
+
+export function outcome(config, session, env) {
+  return new Promise((resolve) => {
+    const { value } = session || {};
+
+    if (!session || !value) {
+      resolve({ score: 0, scoreA: 0, scoreB: 0, empty: true, logTrace: ['Student did not answer the question.'] });
+    }
+
+    if (value) {
+      const { partA, partB } = value || {};
+
+      const partialScoringEnabled = partialScoring.enabled(config, env);
+
+      const scoreA = getScore(config, partA, 'partA', partialScoringEnabled);
+      const scoreB = getScore(config, partB, 'partB', partialScoringEnabled);
+      const logTrace = getLogTrace(config, session, env);
+
+      if (!partialScoringEnabled) {
+        // The EBSR item is worth 1 point
+        // That point is awarded if and only if both parts are fully correct, otherwise no points are awarded
+        resolve({ score: scoreA === 1 && scoreB === 1 ? 1 : 0, scoreA, scoreB, max: 1, logTrace });
+      } else {
+        // The EBSR item is worth 2 points
+        if (scoreA === 1) {
+          if (scoreB === 1) {
+            // If Part A and Part B are both correct, 2 points are awarded
+            resolve({ score: 2, scoreA, scoreB, max: 2, logTrace });
+          } else {
+            // If Part A is correct and part B is incorrect, 1 point is awarded
+            resolve({ score: 1, scoreA, scoreB, max: 2, logTrace });
+          }
+        } else {
+          // For all other combinations, no points are awarded
+          resolve({ score: 0, scoreA, scoreB, max: 2, logTrace });
+        }
+      }
+    }
+  });
+}
+
+const returnPartCorrect = (choices) => {
+  let answers = [];
+
+  choices.forEach((i) => {
+    const { correct, value } = i;
+    if (correct) {
+      answers.push(value);
+    }
+  });
+  return answers;
+};
+
+export const createCorrectResponseSession = (question, env) => {
+  return new Promise((resolve) => {
+    if (env.mode !== 'evaluate' && env.role === 'instructor') {
+      const { partA, partB } = question;
+
+      const partACorrect = returnPartCorrect(partA.choices);
+      const partBCorrect = returnPartCorrect(partB.choices);
+
+      resolve({
+        value: {
+          partA: {
+            id: 'partA',
+            value: partACorrect,
+          },
+          partB: {
+            id: 'partB',
+            value: partBCorrect,
+          },
+        },
+        id: '1',
+      });
+    } else {
+      resolve(null);
+    }
+  });
+};
+
+// remove all html tags
+const getInnerText = (html) => (html || '').replaceAll(/<[^>]*>/g, '');
+
+// remove all html tags except img, iframe and source tag for audio
+const getContent = (html) => (html || '').replace(/(<(?!img|iframe|source)([^>]+)>)/gi, '');
+
+const validatePart = (model = {}, config = {}) => {
+  const { choices } = model;
+  const { minAnswerChoices = 2, maxAnswerChoices } = config;
+  const reversedChoices = [...(choices || [])].reverse();
+  const errors = {};
+  const choicesErrors = {};
+  const rationaleErrors = {};
+  let hasCorrectResponse = false;
+
+  ['teacherInstructions', 'prompt'].forEach((field) => {
+    if (config[field]?.required && !getContent(model[field])) {
+      errors[field] = 'This field is required.';
+    }
+  });
+
+  reversedChoices.forEach((choice, index) => {
+    const { correct, value, label, rationale } = choice;
+
+    if (correct) {
+      hasCorrectResponse = true;
+    }
+
+    if (!getContent(label)) {
+      choicesErrors[value] = 'Content should not be empty.';
+    } else {
+      const identicalAnswer = reversedChoices.slice(index + 1).some((c) => c.label === label);
+
+      if (identicalAnswer) {
+        choicesErrors[value] = 'Content should be unique.';
+      }
+    }
+
+    if (config.rationale?.required && !getContent(rationale)) {
+      rationaleErrors[value] = 'This field is required.';
+    }
+  });
+
+  const nbOfChoices = (choices || []).length;
+
+  if (nbOfChoices < minAnswerChoices) {
+    errors.answerChoices = `There should be at least ${minAnswerChoices} choices defined.`;
+  } else if (nbOfChoices > maxAnswerChoices) {
+    errors.answerChoices = `No more than ${maxAnswerChoices} choices should be defined.`;
+  }
+
+  if (!hasCorrectResponse) {
+    errors.correctResponse = 'No correct response defined.';
+  }
+
+  if (!isEmpty(choicesErrors)) {
+    errors.choices = choicesErrors;
+  }
+
+  if (!isEmpty(rationaleErrors)) {
+    errors.rationale = rationaleErrors;
+  }
+
+  return errors;
+};
+
+export const validate = (model = {}, config = {}) => {
+  const { partA, partB } = model || {};
+  const { partA: partAConfig, partB: partBConfig } = config || {};
+
+  const partAErrors = validatePart(partA, partAConfig);
+  const partBErrors = validatePart(partB, partBConfig);
+
+  return { partA: partAErrors, partB: partBErrors };
+};

package/src/controller/utils.ts

@@ -0,0 +1,28 @@
+// @ts-nocheck
+/**
+ * @synced-from pie-elements/packages/ebsr/controller/src/utils.js
+ * @auto-generated
+ *
+ * This file is automatically synced from pie-elements and converted to TypeScript.
+ * Manual edits will be overwritten on next sync.
+ * To make changes, edit the upstream JavaScript file and run sync again.
+ */
+
+import { isEqual } from 'lodash-es';
+
+export const getCorrectResponse = (choices) =>
+  choices &&
+  choices
+    .filter((c) => c.correct)
+    .map((c) => c.value)
+    .sort();
+
+export const isResponseCorrect = (question, key, session) => {
+  let correctResponse = getCorrectResponse(question.choices);
+
+  if (session && session.value) {
+    return isEqual((session.value[key].value || []).sort(), correctResponse);
+  }
+
+  return false;
+};

package/src/delivery/index.tsx

@@ -0,0 +1,167 @@
+// @ts-nocheck
+/**
+ * @synced-from pie-elements/packages/ebsr/src/index.js
+ * @auto-generated
+ *
+ * This file is automatically synced from pie-elements and converted to TypeScript.
+ * Manual edits will be overwritten on next sync.
+ * To make changes, edit the upstream JavaScript file and run sync again.
+ */
+
+import { SessionChangedEvent } from '@pie-element/shared-player-events';
+import MultipleChoice from '@pie-element/multiple-choice';
+import { get } from 'lodash-es';
+import debug from 'debug';
+
+const SESSION_CHANGED = SessionChangedEvent.TYPE;
+const MC_TAG_NAME = 'ebsr-multiple-choice';
+const log = debug('pie-elements:ebsr');
+
+class EbsrMC extends MultipleChoice {}
+
+const defineMultipleChoice = () => {
+  if (!customElements.get(MC_TAG_NAME)) {
+    customElements.define(MC_TAG_NAME, EbsrMC);
+  }
+};
+
+defineMultipleChoice();
+
+const isNonEmptyArray = (a) => Array.isArray(a) && a.length > 0;
+
+export const isSessionComplete = (session) => {
+  const a = get(session, 'value.partA.value');
+  const b = get(session, 'value.partB.value');
+
+  return isNonEmptyArray(a) && isNonEmptyArray(b);
+};
+
+export default class Ebsr extends HTMLElement {
+  constructor() {
+    super();
+    this._model = {};
+    this._session = {};
+  }
+
+  onSessionUpdated: any = (e) => {
+    if (e.target === this) {
+      return;
+    }
+
+    e.preventDefault();
+    e.stopImmediatePropagation();
+
+    const id = e.target.getAttribute('id');
+
+    if (id) {
+      const key = `part${id.toUpperCase()}`;
+
+      if (e.update) {
+        this._model[key] = e.update;
+      }
+      //TODO: accessing a private property here. The session event should contain the update in future to prevent this.
+      this.dispatchSessionChanged(e.srcElement._session, key);
+    }
+  };
+
+  set model(m) {
+    this._model = m;
+
+    customElements.whenDefined(MC_TAG_NAME).then(() => {
+      this.setPartModel(this.partA, 'partA');
+      this.setPartModel(this.partB, 'partB');
+    });
+  }
+
+  set session(s) {
+    this._session = s;
+
+    customElements.whenDefined(MC_TAG_NAME).then(() => {
+      this.setPartSession(this.partA, 'partA');
+      this.setPartSession(this.partB, 'partB');
+    });
+  }
+
+  get session() {
+    return this._session;
+  }
+
+  setPartModel(part, key) {
+    if (this._model && this._model[key] && part) {
+      const { mode } = this._model;
+
+      part.model = {
+        ...this._model[key],
+        mode,
+        keyMode: this._model[key].choicePrefix,
+      };
+    }
+  }
+
+  setPartSession(part, key) {
+    if (this._session && this._model && part) {
+      const { value } = this._session;
+      part.session = value && value[key] ? value[key] : { id: key };
+    }
+  }
+
+  dispatchSessionChanged(partSession, key) {
+    this._session.value = {
+      ...this._session.value,
+      [key]: partSession,
+    };
+
+    log('[onSessionChanged] session: ', this._session);
+    const complete = isSessionComplete(this._session);
+    this.dispatchEvent(new SessionChangedEvent(this.tagName.toLowerCase(), complete));
+  }
+
+  get partA() {
+    return this.querySelector(`${MC_TAG_NAME}#a`);
+  }
+
+  get partB() {
+    return this.querySelector(`${MC_TAG_NAME}#b`);
+  }
+
+  connectedCallback() {
+    this._render();
+    this.addEventListener(SESSION_CHANGED, this.onSessionUpdated);
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener(SESSION_CHANGED, this.onSessionUpdated);
+  }
+
+  _render() {
+    this.ariaLabel = 'Two-Part Question';
+    this.role = 'region';
+    this.innerHTML = `
+      <style>
+        .srOnly {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        padding: 0;
+        margin: -1px;
+        overflow: hidden;
+        left: -10000px;
+        top: auto;
+      }
+      ${this._model?.extraCSSRules?.rules}
+      </style>
+        <h2 class="srOnly">Two-Part Question</h2>
+        <${MC_TAG_NAME} id="a"></${MC_TAG_NAME}>
+        <${MC_TAG_NAME} id="b"></${MC_TAG_NAME}>
+    `;
+
+    // when item is re-rendered (due to connectedCallback), if the custom element is already defined,
+    // we need to set the model and session, otherwise the setters are not reached again
+    if (customElements.get(MC_TAG_NAME)) {
+      this.setPartModel(this.partA, 'partA');
+      this.setPartModel(this.partB, 'partB');
+      this.setPartSession(this.partA, 'partA');
+      this.setPartSession(this.partB, 'partB');
+    }
+  }
+}

package/src/index.iife.ts

@@ -0,0 +1,16 @@
+/**
+ * IIFE entry point for ebsr element
+ * This file is only used for IIFE builds and includes auto-registration
+ *
+ * @sync-generated - Auto-generated during sync from pie-elements
+ */
+
+import Element from './index.js';
+
+// Auto-register the custom element for IIFE mode
+if (typeof window !== 'undefined' && !customElements.get('ebsr-element')) {
+  customElements.define('ebsr-element', Element);
+}
+
+// Export for IIFE global
+export default Element;

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from './delivery/index.js';