@pie-element/categorize 0.1.0

package/src/controller/index.ts

@@ -0,0 +1,469 @@
+// @ts-nocheck
+/**
+ * @synced-from pie-elements/packages/categorize/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 { isEmpty } from 'lodash-es';
+import { buildState, score } from '@pie-lib/categorize';
+import { getFeedbackForCorrectness } from '@pie-element/shared-feedback';
+import { lockChoices, getShuffledChoices, partialScoring } from '@pie-element/shared-controller-utils';
+import Translator from '@pie-lib/translator';
+
+const { translator } = Translator;
+import defaults from './defaults.js';
+import { getCompleteResponseDetails, isAlternateDuplicated, isCorrectResponseDuplicated } from './utils.js';
+
+// eslint-disable-next-line no-console
+
+export { score };
+
+export const getPartialScore = (correctResponse, builtCategories) => {
+  // in the resulted best scenario we make a sum with all the correct responses
+  // and all the placements
+  const { placements, score } = builtCategories.reduce(
+    (acc, { choices = [] }) => ({
+      placements: acc.placements + choices.length,
+      score: acc.score + choices.filter((ch) => ch.correct).length,
+    }),
+    { placements: 0, score: 0 },
+  );
+
+  // in the correct response, we make a sum of the max possible score
+  const { maxScore } = correctResponse.reduce(
+    (acc, { choices }) => ({
+      maxScore: acc.maxScore + choices.length,
+    }),
+    { maxScore: 0 },
+  );
+
+  // if there are any extra placements, we subtract from the obtained score
+  const extraPlacements = placements > maxScore ? placements - maxScore : 0;
+  const totalScore = (score - extraPlacements) / maxScore;
+
+  return totalScore < 0 ? 0 : parseFloat(totalScore.toFixed(2));
+};
+
+const getAlternates = (correctResponse) =>
+  correctResponse.map((c) => c.alternateResponses).filter((alternate) => alternate);
+
+export const getTotalScore = (question, session, env) => {
+  if (!session) {
+    return 0;
+  }
+
+  if (Object.keys(session).length === 0) {
+    return 0;
+  }
+  const { categories, choices } = question || {};
+  let { correctResponse } = question || {};
+  let { answers } = session || {};
+  answers = answers || [];
+  correctResponse = correctResponse || [];
+
+  // this function is used in pie-ui/categorize as well, in order to get the best scenario
+  // so we get the best scenario and calculate the score
+  const { categories: builtCategories, correct } = buildState(categories, choices, answers, correctResponse);
+
+  const alternates = getAlternates(correctResponse);
+  const enabled = partialScoring.enabled(question, env);
+
+  // if there are any alternates, there will be no partial scoring!
+  if (enabled && !alternates.length) {
+    // we apply partial scoring
+    return getPartialScore(correctResponse, builtCategories);
+  }
+
+  // else we apply dichotomous
+  return correct ? 1 : 0;
+};
+
+export const getCorrectness = (question, session, env) => {
+  return new Promise((resolve) => {
+    if (env.mode === 'evaluate') {
+      const score = getTotalScore(question, session, env);
+      if (score === 1) {
+        resolve('correct');
+      } else if (score === 0) {
+        resolve('incorrect');
+      } else {
+        resolve('partially-correct');
+      }
+    } else {
+      resolve(undefined);
+    }
+  });
+};
+
+export const createDefaultModel = (model = {}) =>
+  new Promise((resolve) => {
+    resolve({
+      ...defaults,
+      ...model,
+    });
+  });
+
+export const normalize = (question) => ({ ...defaults, ...question });
+
+/**
+ *
+ * @param {*} question
+ * @param {*} session
+ * @param {*} env
+ * @param {*} updateSession - optional - a function that will set the properties passed into it on the session.
+ */
+export const model = async (question, session, env, updateSession) => {
+  const normalizedQuestion = normalize(question);
+  const answerCorrectness = await getCorrectness(normalizedQuestion, session, env);
+
+  const { mode, role } = env || {};
+
+  const {
+    categories,
+    categoriesPerRow,
+    choicesLabel,
+    choicesPosition,
+    correctResponse,
+    feedback,
+    feedbackEnabled,
+    promptEnabled,
+    prompt,
+    rowLabels,
+    rationaleEnabled,
+    rationale,
+    teacherInstructionsEnabled,
+    teacherInstructions,
+    language,
+    maxChoicesPerCategory,
+    extraCSSRules,
+    minRowHeight,
+    fontSizeFactor,
+    autoplayAudioEnabled,
+    completeAudioEnabled,
+    customAudioButton,
+  } = normalizedQuestion;
+  let { choices, note } = normalizedQuestion;
+  let fb;
+
+  const lockChoiceOrder = lockChoices(normalizedQuestion, session, env);
+
+  const filteredCorrectResponse = correctResponse.map((response) => {
+    const filteredChoices = (response.choices || []).filter((choice) => choice !== 'null');
+    return { ...response, choices: filteredChoices };
+  });
+
+  if (mode === 'evaluate' && feedbackEnabled) {
+    fb = await getFeedbackForCorrectness(answerCorrectness, feedback);
+  }
+
+  if (!lockChoiceOrder) {
+    choices = await getShuffledChoices(choices, session, updateSession, 'id');
+  }
+
+  if (!note) {
+    note = translator.t('common:commonCorrectAnswerWithAlternates', { lng: language });
+  }
+
+  const alternates = getAlternates(filteredCorrectResponse);
+  const { responseAreasToBeFilled, possibleResponses, hasUnplacedChoices } = getCompleteResponseDetails(
+    filteredCorrectResponse,
+    normalizedQuestion.allowAlternateEnabled ? alternates : [],
+    normalizedQuestion.choices,
+  );
+  const out = {
+    categories: categories || [],
+    categoriesPerRow: categoriesPerRow || 2,
+    maxChoicesPerCategory,
+    correctness: answerCorrectness,
+    choices: choices || [],
+    choicesLabel: choicesLabel || '',
+    choicesPosition,
+    disabled: mode !== 'gather',
+    feedback: fb,
+    lockChoiceOrder,
+    prompt: promptEnabled ? prompt : null,
+    rowLabels,
+    note,
+    env,
+    showNote: alternates && alternates.length > 0,
+    correctResponse: mode === 'evaluate' ? filteredCorrectResponse : undefined,
+    language,
+    extraCSSRules,
+    fontSizeFactor,
+    minRowHeight: minRowHeight,
+    autoplayAudioEnabled,
+    completeAudioEnabled,
+    customAudioButton,
+    possibleResponses,
+    responseAreasToBeFilled,
+    hasUnplacedChoices,
+  };
+
+  if (role === 'instructor' && (mode === 'view' || mode === 'evaluate')) {
+    out.rationale = rationaleEnabled ? rationale : null;
+    out.teacherInstructions = teacherInstructionsEnabled ? teacherInstructions : null;
+  } else {
+    out.rationale = null;
+    out.teacherInstructions = null;
+  }
+
+  return out;
+};
+
+  /**
+ * Generates detailed trace log for scoring evaluation
+ * @param {Object} model - the question model
+ * @param {Object} session - the student session
+ * @param {Object} env - the environment
+ * @returns {Array} traceLog - array of trace messages
+ */
+export const getLogTrace = (model, session, env) => {
+  const traceLog = [];
+  const { answers } = session || {};
+  const { categories, choices, correctResponse } = model || {};
+
+  const draggedChoices = answers.reduce(
+    (sum, a) => sum + (a.choices?.length || 0),
+    0
+  );
+
+  const alternates = getAlternates(correctResponse);
+  const hasAlternates = alternates.length > 0;
+  const partialScoringEnabled = partialScoring.enabled(model, env);
+
+  const builtState =
+    draggedChoices > 0
+      ? buildState(categories, choices, answers, correctResponse)
+      : null;
+
+  const builtCategories = builtState?.categories || [];
+  
+  if (draggedChoices > 0) {
+    traceLog.push(`Student placed ${draggedChoices} choice(s) into categories.`);
+        
+    (categories || []).forEach((category, categoryIndex) => {
+      const categoryId = category.id;
+      const builtCategory = builtCategories.find(c => c.id === categoryId);
+      const studentChoices = builtCategory ? builtCategory.choices || [] : [];
+      const correctResponseForCategory = (correctResponse || []).find(cr => cr.category === categoryId);
+      const expectedChoices = correctResponseForCategory ? correctResponseForCategory.choices || [] : [];
+      
+      if (expectedChoices.length > 0) {
+        if (studentChoices.length === 0) {
+          traceLog.push(`Category ${categoryId}: student left empty (should contain ${expectedChoices.length} choice(s)).`);
+        } else {
+          const correctCount = studentChoices.filter(choice => choice.correct).length;
+          const incorrectCount = studentChoices.length - correctCount;
+          
+          if (correctCount > 0 && incorrectCount === 0) {
+            traceLog.push(`Category ${categoryId}: student placed ${correctCount} correct choice(s).`);
+          } else if (correctCount === 0 && incorrectCount > 0) {
+            traceLog.push(`Category ${categoryId}: student placed ${incorrectCount} incorrect choice(s).`);
+          } else {
+            traceLog.push(`Category ${categoryId}: student placed ${correctCount} correct and ${incorrectCount} incorrect choice(s).`);
+          }
+        }
+      }
+    });
+  } else {
+    traceLog.push('Student did not place any choices into categories.');
+  }
+
+  if (hasAlternates) {
+    traceLog.push(`Alternate response combinations are accepted for this question.`);
+  }
+
+  if (hasAlternates) {
+    traceLog.push(`Score calculated using all-or-nothing scoring (alternate responses disable partial scoring).`);
+    traceLog.push(`Student must get all categories completely correct to receive full credit.`);
+  } else if (partialScoringEnabled) {
+    traceLog.push(`Score calculated using partial scoring.`);
+    traceLog.push(`Student receives credit for each correct placement, with deductions for incorrect placements beyond required amount.`);
+    
+    if (draggedChoices > 0) {
+      const totalCorrect = builtCategories.reduce((sum, cat) => 
+        sum + (cat.choices || []).filter(choice => choice.correct).length, 0);
+      const totalIncorrect = draggedChoices - totalCorrect;
+      const maxPossible = (correctResponse || []).reduce((sum, cat) => 
+        sum + (cat.choices || []).length, 0);
+      
+      traceLog.push(`Partial scoring calculation: ${totalCorrect} correct placements, ${totalIncorrect} incorrect placements.`);
+      
+      if (draggedChoices > maxPossible) {
+        const extraPlacements = draggedChoices - maxPossible;
+        traceLog.push(`${extraPlacements} extra placement(s) beyond required amount will be deducted from score.`);
+      }
+    }
+  } else {
+    traceLog.push(`Score calculated using all-or-nothing scoring.`);
+    traceLog.push(`Student must get all categories completely correct to receive full credit.`);
+  }
+
+  const score = getTotalScore(model, session, env);
+  traceLog.push(`Final score: ${score}.`);
+
+  return traceLog;
+}
+
+export const outcome = (question, session, env) => {
+  if (env.mode !== 'evaluate') {
+    return Promise.reject(new Error('Can not call outcome when mode is not evaluate'));
+  } else {
+    return new Promise((resolve) => {
+      if (!session || isEmpty(session)) {
+        resolve({
+          score: 0,
+          empty: true,
+          traceLog: ['Student did not place any choices into categories. Score is 0.'],
+        });
+      } else {
+        const traceLog = getLogTrace(question, session, env);
+        const score = getTotalScore(question, session, env);
+        
+        resolve({
+          score,
+          empty: false,
+          traceLog,
+        });
+      }
+    });
+  }
+};
+
+export const createCorrectResponseSession = (question, env) => {
+  return new Promise((resolve) => {
+    const { mode, role } = env || {};
+
+    if (mode !== 'evaluate' && role === 'instructor') {
+      const { correctResponse } = question;
+
+      resolve({ answers: correctResponse, id: 1 });
+    } else {
+      return 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, '');
+
+export const validate = (model = {}, config = {}) => {
+  const { categories, choices, correctResponse, maxAnswerChoices } = model;
+  const {
+    minChoices = 1,
+    minCategories = 1,
+    maxCategories = 12,
+    maxLengthPerChoice = 300,
+    maxLengthPerCategory = 150,
+  } = config;
+  const reversedChoices = [...(choices || [])].reverse();
+  const errors = {};
+  const choicesErrors = {};
+  const categoriesErrors = {};
+
+  ['teacherInstructions', 'prompt', 'rationale'].forEach((field) => {
+    if (config[field]?.required && !getContent(model[field])) {
+      errors[field] = 'This field is required.';
+    }
+  });
+
+  (categories || []).forEach((category) => {
+    const { id, label } = category;
+
+    if (getInnerText(label).length > maxLengthPerCategory) {
+      categoriesErrors[id] = `Category labels should be no more than ${maxLengthPerCategory} characters long.`;
+    }
+  });
+
+  (reversedChoices || []).forEach((choice, index) => {
+    const { id, content } = choice;
+
+    if (getInnerText(content).length > maxLengthPerChoice) {
+      choicesErrors[id] = `Tokens should be no more than ${maxLengthPerChoice} characters long.`;
+    }
+
+    if (!getContent(content)) {
+      choicesErrors[id] = 'Tokens should not be empty.';
+    } else {
+      const identicalAnswer = reversedChoices.slice(index + 1).some((c) => c.content === content);
+
+      if (identicalAnswer) {
+        choicesErrors[id] = 'Tokens content should be unique.';
+      }
+    }
+  });
+
+  const nbOfCategories = (categories || []).length;
+  const nbOfChoices = (choices || []).length;
+
+  if (nbOfCategories > maxCategories) {
+    errors.categoriesError = `No more than ${maxCategories} categories should be defined.`;
+  } else if (nbOfCategories < minCategories) {
+    errors.categoriesError = `There should be at least ${minCategories} category defined.`;
+  }
+
+  if (nbOfChoices < minChoices) {
+    errors.choicesError = `There should be at least ${minChoices} choices defined.`;
+  } else if (nbOfChoices > maxAnswerChoices) {
+    errors.choicesError = `No more than ${maxAnswerChoices} choices should be defined.`;
+  }
+
+  if (nbOfChoices && nbOfCategories) {
+    let hasAssociations = false;
+
+    (correctResponse || []).forEach((response) => {
+      const { choices = [], alternateResponses = [] } = response;
+
+      if (choices.length) {
+        hasAssociations = true;
+      } else {
+        alternateResponses.forEach((alternate) => {
+          if ((alternate || []).length) {
+            hasAssociations = true;
+          }
+        });
+      }
+    });
+
+    let duplicateAlternateIndex = -1;
+    let duplicateCategory = '';
+    (correctResponse || []).forEach((response) => {
+      const { choices = [], alternateResponses = [], category } = response;
+
+      if (duplicateAlternateIndex === -1) {
+        duplicateAlternateIndex = isCorrectResponseDuplicated(choices, alternateResponses);
+
+        if (duplicateAlternateIndex === -1) {
+          duplicateAlternateIndex = isAlternateDuplicated(alternateResponses);
+        }
+
+        duplicateCategory = category;
+      }
+    });
+
+    if (duplicateAlternateIndex > -1) {
+      errors.duplicateAlternate = { index: duplicateAlternateIndex, category: duplicateCategory };
+    }
+
+    if (!hasAssociations) {
+      errors.associationError = 'At least one token should be assigned to at least one category.';
+    }
+  }
+
+  if (!isEmpty(choicesErrors)) {
+    errors.choicesErrors = choicesErrors;
+  }
+
+  if (!isEmpty(categoriesErrors)) {
+    errors.categoriesErrors = categoriesErrors;
+  }
+
+  return errors;
+};

package/src/controller/utils.ts

@@ -0,0 +1,79 @@
+// @ts-nocheck
+/**
+ * @synced-from pie-elements/packages/categorize/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.
+ */
+
+// used in configure too, for consistency modify it there too
+export const multiplePlacements = { enabled: 'Yes', disabled: 'No', perChoice: 'Set Per Choice' };
+
+// used to validate the config
+export const isCorrectResponseDuplicated = (choices, alternate) => {
+  if (choices.length < 1 || alternate.length < 1) {
+    return -1;
+  }
+
+  const stringChoices = JSON.stringify(choices.sort());
+  const stringAlternate = alternate.reduce(
+    (total, current) => (current.length > 0 ? [...total, JSON.stringify(current.sort())] : total),
+    [],
+  );
+  const foundIndexDuplicate = stringAlternate.findIndex((alternate) => alternate.length && alternate === stringChoices);
+
+  return foundIndexDuplicate;
+};
+
+export const isAlternateDuplicated = (alternate) => {
+  if (alternate.length <= 1) {
+    return -1;
+  }
+
+  const elementSet = new Set();
+  const stringAlternate = alternate.reduce(
+    (total, current) => (current.length > 0 ? [...total, JSON.stringify(current.sort())] : total),
+    [],
+  );
+
+  for (let i = 0; i < stringAlternate.length; i++) {
+    if (elementSet.has(stringAlternate[i]) && stringAlternate[i]) {
+      return i;
+    }
+
+    elementSet.add(stringAlternate[i]);
+  }
+
+  return -1;
+};
+
+// calculate the minimum number of populated response areas (categories) in the correct answer or alternates
+// and create an array with the possible responses ids
+export const getCompleteResponseDetails = (correctResponse, alternates, allChoices) => {
+  const choicesPerCategory = correctResponse.map((category) => category.choices);
+  const possibleResponses = [choicesPerCategory.flat()];
+  let responseAreasToBeFilled = choicesPerCategory.filter((choices) => choices.length).length;
+
+  if (alternates.length) {
+    const alternatesPerChoice = alternates[0]?.length || 0; // number of alternates
+
+    [...Array(alternatesPerChoice).keys()].forEach((index) => {
+      const alternatesPerResponse = alternates.map((alternate) => alternate[index]);
+      const filledCategories = alternatesPerResponse.filter((category) => category?.length).length;
+      possibleResponses.push(alternatesPerResponse.flat());
+
+      if (filledCategories < responseAreasToBeFilled) {
+        responseAreasToBeFilled = filledCategories;
+      }
+    });
+  }
+
+  // check if any correct answer have any unplaced answer choices
+  const hasUnplacedChoices = possibleResponses.some(
+    (response) => !allChoices.every((val) => response.includes(val?.id)),
+  );
+
+  return { responseAreasToBeFilled, possibleResponses, hasUnplacedChoices };
+};

package/src/delivery/categorize/categories.tsx

@@ -0,0 +1,139 @@
+// @ts-nocheck
+/**
+ * @synced-from pie-elements/packages/categorize/src/categorize/categories.jsx
+ * @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 React from 'react';
+import PropTypes from 'prop-types';
+import { styled } from '@mui/material/styles';
+import { color } from '@pie-lib/render-ui';
+
+import GridContent from './grid-content.js';
+import Category, { CategoryType } from './category.js';
+
+export { CategoryType };
+
+export class Categories extends React.Component {
+  static propTypes = {
+    categories: PropTypes.arrayOf(PropTypes.shape(CategoryType)),
+    model: PropTypes.shape({
+      categoriesPerRow: PropTypes.number,
+    }),
+    disabled: PropTypes.bool,
+    onDropChoice: PropTypes.func.isRequired,
+    onRemoveChoice: PropTypes.func.isRequired,
+    rowLabels: PropTypes.array,
+  };
+
+  static defaultProps = {
+    model: {
+      categoriesPerRow: 1,
+    },
+  };
+
+  render() {
+    const { categories, model, disabled, onDropChoice, onRemoveChoice, rowLabels } = this.props;
+    const { categoriesPerRow, minRowHeight } = model;
+
+    // split categories into an array of arrays (inner array),
+    // where each inner array represents how many categories should be displayed on one row
+    const chunkedCategories = [];
+    const cats = categories || [];
+    for (let i = 0; i < cats.length; i += categoriesPerRow) {
+      chunkedCategories.push(cats.slice(i, i + categoriesPerRow));
+    }
+
+    const hasNonEmptyString = (array) => {
+      let found = false;
+
+      (array || []).forEach((element) => {
+        if (typeof element === 'string' && element.trim() !== '' && element.trim() !== '<div></div>') {
+          found = true;
+        }
+      });
+
+      return found;
+    };
+
+    return (
+      <GridContent
+        columns={categoriesPerRow}
+        rows={Math.ceil(categories.length / categoriesPerRow) * 2}
+        extraStyle={{ flex: 1 }}
+      >
+        {chunkedCategories.map((cat, rowIndex) => {
+          let items = [];
+
+          // for each inner array of categories, create a row with category titles
+          // first cell of row has to be the row label
+          cat.forEach((c, columnIndex) => {
+            items.push(
+              <div style={{ display: 'flex' }}>
+                {columnIndex === 0 && hasNonEmptyString(rowLabels) ? (
+                  <StyledRowLabel
+                    key={rowIndex}
+                    dangerouslySetInnerHTML={{
+                      __html: rowLabels[rowIndex] || '',
+                    }}
+                  />
+                ) : null}
+                <StyledCategoryWrapper>
+                  <StyledLabel
+                    key={`category-label-${rowIndex}-${columnIndex}`}
+                    dangerouslySetInnerHTML={{ __html: c.label }}
+                  />
+
+                  <Category
+                    minRowHeight={minRowHeight}
+                    onDropChoice={(h) => onDropChoice(c.id, h)}
+                    onRemoveChoice={onRemoveChoice}
+                    disabled={disabled}
+                    key={`category-element-${rowIndex}-${columnIndex}`}
+                    {...c}
+                  />
+                </StyledCategoryWrapper>
+              </div>,
+            );
+          });
+
+          // if the last row has fewer categories than max on a row, fill the spaces with divs
+          items = items.concat(
+            Array(categoriesPerRow - cat.length)
+              .fill(<div />)
+              .map((value, index) => <div key={`fill-space-final-${index}`} />),
+          );
+
+          return items;
+        })}
+      </GridContent>
+    );
+  }
+}
+
+const StyledLabel: any = styled('div')(({ theme }) => ({
+  color: color.text(),
+  backgroundColor: color.background(),
+  textAlign: 'center',
+  paddingTop: theme.spacing(1),
+}));
+
+const StyledRowLabel: any = styled('div')({
+  alignItems: 'center',
+  display: 'flex',
+  justifyContent: 'center',
+  flex: 0.5,
+  marginRight: '12px',
+});
+
+const StyledCategoryWrapper: any = styled('div')({
+  display: 'flex',
+  flex: '2',
+  flexDirection: 'column',
+});
+
+export default Categories;