From 75401e13eef730db291e561a39844e59cebde55e Mon Sep 17 00:00:00 2001
From: Tom <20648924+moT01@users.noreply.github.com>
Date: Fri, 4 Oct 2024 12:59:50 -0500
Subject: [PATCH] feat(client, challenge-parser): add explanation to challenges
 (#56472)

---
 client/gatsby-node.js                         |   1 +
 client/i18n/locales/english/translations.json |   1 +
 client/src/redux/prop-types.ts                |   1 +
 .../components/challenge-explanation.css      |   3 +
 .../components/challenge-explanation.tsx      |  29 +++++
 .../Challenges/fill-in-the-blank/show.tsx     |  12 ++-
 client/src/templates/Challenges/odin/show.tsx |  12 ++-
 .../meta.json                                 |   8 ++
 .../66a909dc2e382527ead44c23.md               | 101 ++++++++++++++++++
 .../66a90bbd872bca2a1b7e63a9.md               |  80 ++++++++++++++
 .../challenge-schema.test.js.snap             |   5 +
 curriculum/schema/challenge-schema.js         |   5 +
 tools/challenge-parser/parser/index.js        |   2 +-
 13 files changed, 255 insertions(+), 5 deletions(-)
 create mode 100644 client/src/templates/Challenges/components/challenge-explanation.css
 create mode 100644 client/src/templates/Challenges/components/challenge-explanation.tsx
 create mode 100644 curriculum/challenges/english/24-b1-english-for-developers/learn-how-to-describe-places-and-events/66a909dc2e382527ead44c23.md
 create mode 100644 curriculum/challenges/english/24-b1-english-for-developers/learn-how-to-describe-places-and-events/66a90bbd872bca2a1b7e63a9.md

diff --git a/client/gatsby-node.js b/client/gatsby-node.js
index 61da002e38f..30a2849bce3 100644
--- a/client/gatsby-node.js
+++ b/client/gatsby-node.js
@@ -261,6 +261,7 @@ exports.createSchemaCustomization = ({ actions }) => {
     type Challenge {
       blockType: String
       challengeFiles: [FileContents]
+      explanation: String
       notes: String
       url: String
       assignments: [String]
diff --git a/client/i18n/locales/english/translations.json b/client/i18n/locales/english/translations.json
index fcedea63ba7..9a1cae4d2da 100644
--- a/client/i18n/locales/english/translations.json
+++ b/client/i18n/locales/english/translations.json
@@ -388,6 +388,7 @@
     "assignment-not-complete": "Please complete the assignments",
     "assignments": "Assignments",
     "question": "Question",
+    "explanation": "Explanation",
     "solution-link": "Solution Link",
     "source-code-link": "Source Code Link",
     "ms-link": "Microsoft Link",
diff --git a/client/src/redux/prop-types.ts b/client/src/redux/prop-types.ts
index 3e14958775b..7c135d1fc58 100644
--- a/client/src/redux/prop-types.ts
+++ b/client/src/redux/prop-types.ts
@@ -174,6 +174,7 @@ export type ChallengeNode = {
     demoType: 'onClick' | 'onLoad' | null;
     description: string;
     challengeFiles: ChallengeFiles;
+    explanation: string;
     fields: Fields;
     fillInTheBlank: FillInTheBlank;
     forumTopicId: number;
diff --git a/client/src/templates/Challenges/components/challenge-explanation.css b/client/src/templates/Challenges/components/challenge-explanation.css
new file mode 100644
index 00000000000..c9fd943be59
--- /dev/null
+++ b/client/src/templates/Challenges/components/challenge-explanation.css
@@ -0,0 +1,3 @@
+.explanation {
+  cursor: pointer;
+}
diff --git a/client/src/templates/Challenges/components/challenge-explanation.tsx b/client/src/templates/Challenges/components/challenge-explanation.tsx
new file mode 100644
index 00000000000..ed211c34216
--- /dev/null
+++ b/client/src/templates/Challenges/components/challenge-explanation.tsx
@@ -0,0 +1,29 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import Spacer from '../../../components/helpers/spacer';
+import PrismFormatted from './prism-formatted';
+
+interface ChallengeExplanationProps {
+  explanation: string;
+}
+
+function ChallengeExplanation({
+  explanation
+}: ChallengeExplanationProps): JSX.Element {
+  const { t } = useTranslation();
+
+  return (
+    <>
+      <details className='explanation'>
+        <summary>{t('learn.explanation')}</summary>
+        <Spacer size='medium' />
+        <PrismFormatted className={'line-numbers'} text={explanation} />
+      </details>
+      <Spacer size='medium' />
+    </>
+  );
+}
+
+ChallengeExplanation.displayName = 'ChallengeExplanation';
+
+export default ChallengeExplanation;
diff --git a/client/src/templates/Challenges/fill-in-the-blank/show.tsx b/client/src/templates/Challenges/fill-in-the-blank/show.tsx
index 3fd482c6347..5db70d0d607 100644
--- a/client/src/templates/Challenges/fill-in-the-blank/show.tsx
+++ b/client/src/templates/Challenges/fill-in-the-blank/show.tsx
@@ -18,6 +18,7 @@ import LearnLayout from '../../../components/layouts/learn';
 import { ChallengeNode, ChallengeMeta, Test } from '../../../redux/prop-types';
 import Hotkeys from '../components/hotkeys';
 import ChallengeTitle from '../components/challenge-title';
+import ChallegeExplanation from '../components/challenge-explanation';
 import CompletionModal from '../components/completion-modal';
 import HelpModal from '../components/help-modal';
 import FillInTheBlanks from '../components/fill-in-the-blanks';
@@ -60,7 +61,6 @@ const mapDispatchToProps = (dispatch: Dispatch) =>
 interface ShowFillInTheBlankProps {
   challengeMounted: (arg0: string) => void;
   data: { challengeNode: ChallengeNode };
-  description: string;
   isChallengeCompleted: boolean;
   initTests: (xs: Test[]) => void;
   openCompletionModal: () => void;
@@ -250,6 +250,7 @@ class ShowFillInTheBlank extends Component<
             title,
             description,
             instructions,
+            explanation,
             superBlock,
             block,
             translationPending,
@@ -328,7 +329,13 @@ class ShowFillInTheBlank extends Component<
                     handleInputChange={this.handleInputChange}
                   />
                 </ObserveKeys>
-                <Spacer size='medium' />
+
+                {explanation ? (
+                  <ChallegeExplanation explanation={explanation} />
+                ) : (
+                  <Spacer size='medium' />
+                )}
+
                 <Button
                   block={true}
                   variant='primary'
@@ -368,6 +375,7 @@ export const query = graphql`
         title
         description
         instructions
+        explanation
         challengeType
         helpCategory
         superBlock
diff --git a/client/src/templates/Challenges/odin/show.tsx b/client/src/templates/Challenges/odin/show.tsx
index 91c0bc2845f..3d22cbf8592 100644
--- a/client/src/templates/Challenges/odin/show.tsx
+++ b/client/src/templates/Challenges/odin/show.tsx
@@ -23,6 +23,7 @@ import HelpModal from '../components/help-modal';
 import Scene from '../components/scene/scene';
 import PrismFormatted from '../components/prism-formatted';
 import ChallengeTitle from '../components/challenge-title';
+import ChallegeExplanation from '../components/challenge-explanation';
 import MultipleChoiceQuestions from '../components/multiple-choice-questions';
 import Assignments from '../components/assignments';
 import {
@@ -62,7 +63,6 @@ const mapDispatchToProps = (dispatch: Dispatch) =>
 interface ShowOdinProps {
   challengeMounted: (arg0: string) => void;
   data: { challengeNode: ChallengeNode };
-  description: string;
   initTests: (xs: Test[]) => void;
   isChallengeCompleted: boolean;
   openCompletionModal: () => void;
@@ -231,6 +231,7 @@ class ShowOdin extends Component<ShowOdinProps, ShowOdinState> {
             title,
             description,
             instructions,
+            explanation,
             superBlock,
             block,
             videoId,
@@ -336,7 +337,13 @@ class ShowOdin extends Component<ShowOdinProps, ShowOdinState> {
                     handleOptionChange={this.handleOptionChange}
                   />
                 </ObserveKeys>
-                <Spacer size='medium' />
+
+                {explanation ? (
+                  <ChallegeExplanation explanation={explanation} />
+                ) : (
+                  <Spacer size='medium' />
+                )}
+
                 <Button
                   block={true}
                   size='medium'
@@ -398,6 +405,7 @@ export const query = graphql`
         title
         description
         instructions
+        explanation
         challengeType
         helpCategory
         superBlock
diff --git a/curriculum/challenges/_meta/learn-how-to-describe-places-and-events/meta.json b/curriculum/challenges/_meta/learn-how-to-describe-places-and-events/meta.json
index 4a4cd7b23e5..6ece0c7f302 100644
--- a/curriculum/challenges/_meta/learn-how-to-describe-places-and-events/meta.json
+++ b/curriculum/challenges/_meta/learn-how-to-describe-places-and-events/meta.json
@@ -8,6 +8,14 @@
     {
       "id": "66607e5b317411dd5e8aae22",
       "title": "Dialogue 1: I'm Tom"
+    },
+    {
+      "id": "66a909dc2e382527ead44c23",
+      "title": "Task 1"
+    },
+    {
+      "id": "66a90bbd872bca2a1b7e63a9",
+      "title": "Task 2"
     }
   ],
   "helpCategory": "English"
diff --git a/curriculum/challenges/english/24-b1-english-for-developers/learn-how-to-describe-places-and-events/66a909dc2e382527ead44c23.md b/curriculum/challenges/english/24-b1-english-for-developers/learn-how-to-describe-places-and-events/66a909dc2e382527ead44c23.md
new file mode 100644
index 00000000000..5786b04d650
--- /dev/null
+++ b/curriculum/challenges/english/24-b1-english-for-developers/learn-how-to-describe-places-and-events/66a909dc2e382527ead44c23.md
@@ -0,0 +1,101 @@
+---
+id: 66a909dc2e382527ead44c23
+title: Task 1
+challengeType: 19
+dashedName: task-1
+---
+<!-- (Audio) Bob: Hey Lisa, do you have a minute?  -->
+
+# --instructions--
+
+Listen to the audio and answer the question below.
+
+# --questions--
+
+## --text--
+
+What does Bob want to know from Lisa?
+
+## --answers--
+
+If Lisa can lend him some money.
+
+### --feedback--
+
+His question is not about borrowing money.
+
+---
+
+If Lisa can help him with his project.
+
+### --feedback--
+
+The question is not specifically about a project. It is more general.
+
+---
+
+If Lisa has time to talk.
+
+---
+
+If Lisa is feeling well.
+
+### --feedback--
+
+This question is not about Lisa's health.
+
+## --video-solution--
+
+3
+
+# --explanation--
+
+`Do you have a minute?` is a polite way to ask if someone has time to talk.
+
+# --scene--
+
+```json
+{
+  "setup": {
+    "background": "company2-boardroom.png",
+    "characters": [
+      {
+        "character": "Bob",
+        "position": {
+          "x": 50,
+          "y": 15,
+          "z": 1.2
+        },
+        "opacity": 0
+      }
+    ],
+    "audio": {
+      "filename": "B1_1-1.mp3",
+      "startTime": 1,
+      "startTimestamp": 0,
+      "finishTimestamp": 1.72
+    }
+  },
+  "commands": [
+    {
+      "character": "Bob",
+      "opacity": 1,
+      "startTime": 0
+    },
+    {
+      "character": "Bob",
+      "startTime": 1,
+      "finishTime": 2.72,
+      "dialogue": {
+        "text": "Hey Lisa, do you have a minute?",
+        "align": "center"
+      }
+    },
+    {
+      "character": "Bob",
+      "opacity": 0,
+      "startTime": 3.22
+    }
+  ]
+}
+```
diff --git a/curriculum/challenges/english/24-b1-english-for-developers/learn-how-to-describe-places-and-events/66a90bbd872bca2a1b7e63a9.md b/curriculum/challenges/english/24-b1-english-for-developers/learn-how-to-describe-places-and-events/66a90bbd872bca2a1b7e63a9.md
new file mode 100644
index 00000000000..ca2965fadd9
--- /dev/null
+++ b/curriculum/challenges/english/24-b1-english-for-developers/learn-how-to-describe-places-and-events/66a90bbd872bca2a1b7e63a9.md
@@ -0,0 +1,80 @@
+---
+id: 66a90bbd872bca2a1b7e63a9
+title: Task 2
+challengeType: 22
+dashedName: task-2
+---
+
+<!-- (Audio) Bob: Hey Lisa, do you have a minute?  -->
+
+# --instructions--
+
+Listen to the audio and complete the sentence below.
+
+# --fillInTheBlank--
+
+## --sentence--
+
+`Hey Lisa, BLANK you have a minute?`
+
+## --blanks--
+
+`do`
+
+### --feedback--
+
+This is the auxiliary verb used to form the question.
+
+# --explanation--
+
+The auxiliary verb `do` is used to form questions in the `Present Simple` tense. 
+
+For example, in the question `Do you have a minute?`, `do` is used to ask if someone has time.
+
+# --scene--
+
+```json
+{
+  "setup": {
+    "background": "company2-boardroom.png",
+    "characters": [
+      {
+        "character": "Bob",
+        "position": {
+          "x": 50,
+          "y": 15,
+          "z": 1.2
+        },
+        "opacity": 0
+      }
+    ],
+    "audio": {
+      "filename": "B1_1-1.mp3",
+      "startTime": 1,
+      "startTimestamp": 0,
+      "finishTimestamp": 1.72
+    }
+  },
+  "commands": [
+    {
+      "character": "Bob",
+      "opacity": 1,
+      "startTime": 0
+    },
+    {
+      "character": "Bob",
+      "startTime": 1,
+      "finishTime": 2.72,
+      "dialogue": {
+        "text": "Hey Lisa, do you have a minute?",
+        "align": "center"
+      }
+    },
+    {
+      "character": "Bob",
+      "opacity": 0,
+      "startTime": 3.22
+    }
+  ]
+}
+```
diff --git a/curriculum/schema/__snapshots__/challenge-schema.test.js.snap b/curriculum/schema/__snapshots__/challenge-schema.test.js.snap
index e61aa10494a..9016c5d333f 100644
--- a/curriculum/schema/__snapshots__/challenge-schema.test.js.snap
+++ b/curriculum/schema/__snapshots__/challenge-schema.test.js.snap
@@ -143,6 +143,7 @@ const schema = Joi.object()
       is: [
         challengeTypes.step,
         challengeTypes.video,
+        challengeTypes.multipleChoice,
         challengeTypes.fillInTheBlank
       ],
       then: Joi.string().allow(''),
@@ -150,6 +151,10 @@ const schema = Joi.object()
     }),
     disableLoopProtectTests: Joi.boolean().required(),
     disableLoopProtectPreview: Joi.boolean().required(),
+    explanation: Joi.when('challengeType', {
+      is: [challengeTypes.multipleChoice, challengeTypes.fillInTheBlank],
+      then: Joi.string()
+    }),
     challengeFiles: Joi.array().items(fileJoi),
     guideUrl: Joi.string().uri({ scheme: 'https' }),
     hasEditableBoundaries: Joi.boolean(),
diff --git a/curriculum/schema/challenge-schema.js b/curriculum/schema/challenge-schema.js
index 4ff372f6170..43ca8dc7774 100644
--- a/curriculum/schema/challenge-schema.js
+++ b/curriculum/schema/challenge-schema.js
@@ -140,6 +140,7 @@ const schema = Joi.object()
       is: [
         challengeTypes.step,
         challengeTypes.video,
+        challengeTypes.multipleChoice,
         challengeTypes.fillInTheBlank
       ],
       then: Joi.string().allow(''),
@@ -147,6 +148,10 @@ const schema = Joi.object()
     }),
     disableLoopProtectTests: Joi.boolean().required(),
     disableLoopProtectPreview: Joi.boolean().required(),
+    explanation: Joi.when('challengeType', {
+      is: [challengeTypes.multipleChoice, challengeTypes.fillInTheBlank],
+      then: Joi.string()
+    }),
     challengeFiles: Joi.array().items(fileJoi),
     guideUrl: Joi.string().uri({ scheme: 'https' }),
     hasEditableBoundaries: Joi.boolean(),
diff --git a/tools/challenge-parser/parser/index.js b/tools/challenge-parser/parser/index.js
index 87b6748ec64..a9461ef9688 100644
--- a/tools/challenge-parser/parser/index.js
+++ b/tools/challenge-parser/parser/index.js
@@ -53,7 +53,7 @@ const processor = unified()
   .use(addScene)
   .use(addQuizzes)
   .use(addTests)
-  .use(addText, ['description', 'instructions', 'notes']);
+  .use(addText, ['description', 'instructions', 'notes', 'explanation']);
 
 exports.parseMD = function parseMD(filename) {
   return new Promise((resolve, reject) => {