@zomako/elearning-components 2.0.6 → 2.0.8

package/BranchingScenario/README.md

@@ -0,0 +1,192 @@
+# BranchingScenario
+
+A React component for narrative branching scenarios (choose-your-own-path style). Renders scenario nodes with narrative content and choices, tracks the learner’s path and score, supports conditional choices and outcomes with variable updates, and uses pure CSS for fade/transition animations.
+
+## Features
+
+- **Node-based flow**: Start from a given node and move to the next via choices or outcomes.
+- **Choices and outcomes**: Choices can go directly to the next node or expose multiple outcomes (each with optional `scoreModifier` and `variableUpdates`).
+- **Conditional choices**: Choices can use a `condition(variables)` so only some options are shown.
+- **Path, score, and variables**: Tracks visited node IDs, a numeric score, and a variables object for state.
+- **Endings**: When the current node has `type: 'ending'`, the component calls `onComplete` with the final result.
+- **Animations**: Fade and slide transitions between nodes using CSS only (no JS animation libraries).
+- **Accessibility**: Keyboard operable (Enter/Space on choices and outcomes), ARIA region/live/status and clear labels for content and actions.
+
+## Installation
+
+Use the component from the package or copy the `BranchingScenario` folder into your project. No extra dependencies beyond React.
+
+## Props
+
+The component accepts a single props object of type `BranchingScenarioProps`:
+
+| Prop           | Type     | Description |
+|----------------|----------|-------------|
+| `nodes`        | `Record<string, ScenarioNode>` | Map of node ID → scenario node. |
+| `startNodeId`  | `string` | ID of the node to show first. |
+| `onComplete`   | `(result) => void` | Called when an ending node is reached. |
+
+### Types
+
+**ScenarioNode**
+
+| Field      | Type     | Description |
+|-----------|----------|-------------|
+| `id`      | `string` | Unique node ID. |
+| `type`    | `'scenario' \| 'ending'` | `'ending'` triggers `onComplete` when reached. |
+| `title`   | `string` | Node heading. |
+| `content` | `string` | Narrative text. |
+| `image`   | `string?` | Optional image URL. |
+| `choices` | `Choice[]` | Choices for this node (can be empty for endings). |
+| `feedback`| `string?` | Optional feedback text. |
+
+**Choice**
+
+| Field        | Type     | Description |
+|-------------|----------|-------------|
+| `id`        | `string` | Unique choice ID. |
+| `text`      | `string` | Label shown to the user. |
+| `nextNodeId`| `string` | Node to go to if there are no outcomes. |
+| `condition` | `(variables) => boolean`? | If provided, choice is only shown when this returns `true`. |
+| `outcomes`  | `Outcome[]`? | If present, selecting this choice shows outcome options instead of going directly to `nextNodeId`. |
+
+**Outcome**
+
+| Field            | Type     | Description |
+|------------------|----------|-------------|
+| `id`             | `string` | Unique outcome ID. |
+| `text`           | `string` | Label for this outcome. |
+| `nextNodeId`     | `string` | Node to go to when this outcome is selected. |
+| `scoreModifier`  | `number`? | Added to the running score when selected. |
+| `variableUpdates`| `Record<string, any>`? | Merged into the scenario variables when selected. |
+
+**onComplete result**
+
+- `score`: number (sum of all applied `scoreModifier` values).
+- `path`: string[] (ordered list of visited node IDs).
+- `variables`: Record<string, any> (current variables after all updates).
+
+## Usage example
+
+```tsx
+import BranchingScenario from './BranchingScenario';
+
+const nodes = {
+  start: {
+    id: 'start',
+    type: 'scenario',
+    title: 'The Crossroads',
+    content:
+      'You stand at a crossroads. The left path leads into a dark forest. The right path follows a river.',
+    choices: [
+      {
+        id: 'left',
+        text: 'Take the left path into the forest',
+        nextNodeId: 'forest',
+      },
+      {
+        id: 'right',
+        text: 'Follow the river',
+        nextNodeId: 'river',
+      },
+    ],
+  },
+  forest: {
+    id: 'forest',
+    type: 'scenario',
+    title: 'In the Forest',
+    content: 'You enter the forest. It gets darker. You hear a noise ahead.',
+    choices: [
+      {
+        id: 'investigate',
+        text: 'Investigate the noise',
+        nextNodeId: 'forest-choice',
+        outcomes: [
+          {
+            id: 'find-friend',
+            text: 'You find a lost traveler and gain a companion.',
+            nextNodeId: 'ending-with-friend',
+            scoreModifier: 10,
+            variableUpdates: { companion: true },
+          },
+          {
+            id: 'find-wolf',
+            text: 'A wolf appears. You retreat safely.',
+            nextNodeId: 'ending-forest',
+            scoreModifier: 0,
+          },
+        ],
+      },
+      {
+        id: 'retreat',
+        text: 'Go back to the crossroads',
+        nextNodeId: 'start',
+      },
+    ],
+  },
+  river: {
+    id: 'river',
+    type: 'ending',
+    title: 'By the River',
+    content: 'You follow the river and find a village. Your journey ends here.',
+    choices: [],
+  },
+  'ending-with-friend': {
+    id: 'ending-with-friend',
+    type: 'ending',
+    title: 'Good ending',
+    content: 'You and your companion reach safety. Well done.',
+    choices: [],
+  },
+  ending-forest: {
+    id: 'ending-forest',
+    type: 'ending',
+    title: 'Forest end',
+    content: 'You leave the forest and return to the road.',
+    choices: [],
+  },
+};
+
+function App() {
+  const handleComplete = (result) => {
+    console.log('Scenario complete', result);
+    // result: { score, path, variables }
+  };
+
+  return (
+    <BranchingScenario
+      nodes={nodes}
+      startNodeId="start"
+      onComplete={handleComplete}
+    />
+  );
+}
+```
+
+In this example:
+
+1. The learner starts at `start`, chooses left or right.
+2. In `forest`, choosing “Investigate the noise” shows two outcomes; choosing one applies its `scoreModifier` and `variableUpdates` and navigates to the corresponding node.
+3. “Go back to the crossroads” goes to `start` with no outcomes.
+4. Reaching any node with `type: 'ending'` triggers `onComplete` with the current `score`, `path`, and `variables`.
+
+## Styling
+
+Styles are in `style.module.css`. CSS custom properties (e.g. `--branch-accent`, `--branch-bg`) control colors and spacing. Override them in your own CSS or by wrapping the component in a container with different variables. The narrative block and choice/outcome buttons are clearly separated for readability.
+
+## Accessibility
+
+- The root has `role="region"` and `aria-label="Branching scenario"`.
+- The current node content is in a `role="article"` with `aria-live="polite"` and `aria-atomic="true"`.
+- Choices and outcomes are in `<nav>` elements with `aria-label="Choices"` / `"Outcomes"`.
+- Each choice/outcome is a focusable `<button>`; Enter and Space activate it.
+- Focus is managed by the browser; no custom focus trapping. Ensure the component is in a logical tab order.
+
+## File structure
+
+```
+BranchingScenario/
+├── index.tsx         # Component and exported types
+├── style.module.css  # CSS Modules styles (transitions and layout)
+└── README.md         # This file
+```

package/BranchingScenario/index.tsx

@@ -0,0 +1,237 @@
+import React, { useState, useCallback, useMemo, useEffect, useRef } from 'react';
+import styles from './style.module.css';
+
+export interface Outcome {
+  id: string;
+  text: string;
+  nextNodeId: string;
+  scoreModifier?: number;
+  variableUpdates?: Record<string, unknown>;
+}
+
+export interface Choice {
+  id: string;
+  text: string;
+  nextNodeId: string;
+  condition?: (variables: Record<string, unknown>) => boolean;
+  outcomes?: Outcome[];
+}
+
+export interface ScenarioNode {
+  id: string;
+  type: 'scenario' | 'ending';
+  title: string;
+  content: string;
+  image?: string;
+  choices: Choice[];
+  feedback?: string;
+}
+
+export interface BranchingScenarioProps {
+  nodes: Record<string, ScenarioNode>;
+  startNodeId: string;
+  onComplete: (result: {
+    score: number;
+    path: string[];
+    variables: Record<string, unknown>;
+  }) => void;
+}
+
+interface PendingOutcome {
+  choice: Choice;
+}
+
+const BranchingScenario: React.FC<BranchingScenarioProps> = ({
+  nodes,
+  startNodeId,
+  onComplete,
+}) => {
+  const [currentNodeId, setCurrentNodeId] = useState<string>(startNodeId);
+  const [path, setPath] = useState<string[]>([startNodeId]);
+  const [score, setScore] = useState(0);
+  const [variables, setVariables] = useState<Record<string, unknown>>({});
+  const [pendingOutcome, setPendingOutcome] = useState<PendingOutcome | null>(null);
+  const [isExiting, setIsExiting] = useState(false);
+  const completedRef = useRef(false);
+
+  const currentNode = nodes[currentNodeId];
+  const isEnding = currentNode?.type === 'ending';
+
+  const visibleChoices = useMemo(() => {
+    if (!currentNode?.choices) return [];
+    return currentNode.choices.filter(
+      (c) => !c.condition || c.condition(variables)
+    );
+  }, [currentNode, variables]);
+
+  const handleChoiceSelect = useCallback(
+    (choice: Choice) => {
+      if (choice.outcomes && choice.outcomes.length > 0) {
+        setPendingOutcome({ choice });
+        return;
+      }
+      setIsExiting(true);
+      setTimeout(() => {
+        setPath((p) => [...p, choice.nextNodeId]);
+        setCurrentNodeId(choice.nextNodeId);
+        setPendingOutcome(null);
+        setIsExiting(false);
+      }, 280);
+    },
+    []
+  );
+
+  const handleOutcomeSelect = useCallback(
+    (outcome: Outcome) => {
+      setIsExiting(true);
+      setTimeout(() => {
+        setScore((s) => s + (outcome.scoreModifier ?? 0));
+        if (outcome.variableUpdates && Object.keys(outcome.variableUpdates).length > 0) {
+          setVariables((v) => ({ ...v, ...outcome.variableUpdates }));
+        }
+        setPath((p) => [...p, outcome.nextNodeId]);
+        setCurrentNodeId(outcome.nextNodeId);
+        setPendingOutcome(null);
+        setIsExiting(false);
+      }, 280);
+    },
+    []
+  );
+
+  useEffect(() => {
+    if (isEnding && currentNode && !completedRef.current) {
+      completedRef.current = true;
+      onComplete({ score, path, variables });
+    }
+  }, [isEnding, currentNode, score, path, variables, onComplete]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent, choiceOrOutcome: { nextNodeId: string } | Outcome, handler: () => void) => {
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        handler();
+      }
+    },
+    []
+  );
+
+  if (!currentNode) {
+    return (
+      <div className={styles.wrapper} role="alert">
+        <p className={styles.error}>Invalid scenario: node not found.</p>
+      </div>
+    );
+  }
+
+  const showOutcomes = pendingOutcome !== null;
+  const outcomeList = pendingOutcome?.choice.outcomes ?? [];
+
+  return (
+    <div
+      className={styles.wrapper}
+      role="region"
+      aria-label="Branching scenario"
+    >
+      <div
+        className={`${styles.contentWrap} ${isExiting ? styles.contentExit : styles.contentEnter}`}
+        role="article"
+        aria-live="polite"
+        aria-atomic="true"
+      >
+        <h2 className={styles.title} id="scenario-title">
+          {currentNode.title}
+        </h2>
+
+        {currentNode.image && (
+          <div className={styles.imageWrap}>
+            <img
+              src={currentNode.image}
+              alt=""
+              className={styles.image}
+              loading="lazy"
+            />
+          </div>
+        )}
+
+        <div className={styles.narrative} id="scenario-content">
+          {currentNode.content}
+        </div>
+
+        {currentNode.feedback && (
+          <p
+            className={styles.feedback}
+            role="status"
+            aria-live="polite"
+            id="scenario-feedback"
+          >
+            {currentNode.feedback}
+          </p>
+        )}
+
+        {!showOutcomes && visibleChoices.length > 0 && !isEnding && (
+          <nav
+            className={styles.choicesNav}
+            aria-label="Choices"
+          >
+            <p className={styles.choicesLabel} id="choices-label">
+              What do you do?
+            </p>
+            <ul className={styles.choicesList} role="list">
+              {visibleChoices.map((choice, index) => (
+                <li key={choice.id} className={styles.choiceItem}>
+                  <button
+                    type="button"
+                    className={styles.choiceButton}
+                    onClick={() => handleChoiceSelect(choice)}
+                    onKeyDown={(e) => handleKeyDown(e, choice, () => handleChoiceSelect(choice))}
+                    aria-describedby="scenario-content"
+                    aria-label={choice.text}
+                    data-choice-index={index + 1}
+                  >
+                    {choice.text}
+                  </button>
+                </li>
+              ))}
+            </ul>
+          </nav>
+        )}
+
+        {showOutcomes && outcomeList.length > 0 && (
+          <nav
+            className={styles.outcomesNav}
+            aria-label="Outcomes"
+          >
+            <p className={styles.choicesLabel} id="outcomes-label">
+              What happens?
+            </p>
+            <ul className={styles.choicesList} role="list">
+              {outcomeList.map((outcome, index) => (
+                <li key={outcome.id} className={styles.choiceItem}>
+                  <button
+                    type="button"
+                    className={styles.outcomeButton}
+                    onClick={() => handleOutcomeSelect(outcome)}
+                    onKeyDown={(e) => handleKeyDown(e, outcome, () => handleOutcomeSelect(outcome))}
+                    aria-describedby="scenario-content"
+                    aria-label={outcome.text}
+                    data-outcome-index={index + 1}
+                  >
+                    {outcome.text}
+                  </button>
+                </li>
+              ))}
+            </ul>
+          </nav>
+        )}
+
+        {isEnding && (
+          <p className={styles.endingMessage} role="status" aria-live="polite">
+            You have reached the end of this scenario.
+          </p>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default BranchingScenario;

package/BranchingScenario/style.module.css

@@ -0,0 +1,187 @@
+/* ---- Wrapper ---- */
+.wrapper {
+  --branch-accent: #0f766e;
+  --branch-accent-hover: #0d9488;
+  --branch-bg: #f0fdfa;
+  --branch-card-bg: #ffffff;
+  --branch-border: #ccfbf1;
+  --branch-text: #134e4a;
+  --branch-muted: #5eead4;
+  --branch-narrative-bg: #f8fffe;
+  --branch-radius: 12px;
+  --branch-shadow: 0 4px 20px rgba(15, 118, 110, 0.08);
+  font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;
+  color: var(--branch-text);
+  max-width: 42rem;
+  margin: 0 auto;
+}
+
+/* ---- Content wrapper (fade transitions) ---- */
+.contentWrap {
+  opacity: 1;
+  transform: translateY(0);
+  transition:
+    opacity 0.28s ease-out,
+    transform 0.28s ease-out;
+}
+
+.contentEnter {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+.contentExit {
+  opacity: 0;
+  transform: translateY(-8px);
+  pointer-events: none;
+}
+
+/* ---- Title ---- */
+.title {
+  margin: 0 0 1rem;
+  font-size: 1.5rem;
+  font-weight: 700;
+  line-height: 1.3;
+  color: var(--branch-text);
+}
+
+/* ---- Image ---- */
+.imageWrap {
+  margin-bottom: 1.25rem;
+  border-radius: var(--branch-radius);
+  overflow: hidden;
+  box-shadow: var(--branch-shadow);
+  background: var(--branch-border);
+}
+
+.image {
+  display: block;
+  width: 100%;
+  height: auto;
+  vertical-align: middle;
+}
+
+/* ---- Narrative ---- */
+.narrative {
+  padding: 1.25rem 1.5rem;
+  margin-bottom: 1.5rem;
+  background: var(--branch-narrative-bg);
+  border: 1px solid var(--branch-border);
+  border-radius: var(--branch-radius);
+  font-size: 1.0625rem;
+  line-height: 1.65;
+  color: var(--branch-text);
+  transition: opacity 0.28s ease-out;
+}
+
+/* ---- Feedback ---- */
+.feedback {
+  margin: 0 0 1rem;
+  padding: 0.75rem 1rem;
+  font-size: 0.9375rem;
+  line-height: 1.5;
+  color: var(--branch-text);
+  background: var(--branch-bg);
+  border-left: 4px solid var(--branch-accent);
+  border-radius: 0 var(--branch-radius) var(--branch-radius) 0;
+}
+
+/* ---- Choices / Outcomes nav ---- */
+.choicesNav,
+.outcomesNav {
+  margin-top: 1.5rem;
+}
+
+.choicesLabel {
+  margin: 0 0 0.75rem;
+  font-size: 0.875rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--branch-accent);
+}
+
+.choicesList {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.choiceItem {
+  margin: 0;
+}
+
+/* ---- Choice buttons ---- */
+.choiceButton,
+.outcomeButton {
+  display: block;
+  width: 100%;
+  padding: 1rem 1.25rem;
+  font-size: 1rem;
+  font-weight: 500;
+  line-height: 1.4;
+  text-align: left;
+  color: var(--branch-text);
+  background: var(--branch-card-bg);
+  border: 2px solid var(--branch-border);
+  border-radius: var(--branch-radius);
+  cursor: pointer;
+  transition:
+    background-color 0.2s ease,
+    border-color 0.2s ease,
+    transform 0.2s ease,
+    box-shadow 0.2s ease;
+  appearance: none;
+}
+
+.choiceButton:hover,
+.outcomeButton:hover {
+  background: var(--branch-bg);
+  border-color: var(--branch-accent);
+  box-shadow: 0 2px 12px rgba(15, 118, 110, 0.12);
+}
+
+.choiceButton:focus-visible,
+.outcomeButton:focus-visible {
+  outline: 2px solid var(--branch-accent);
+  outline-offset: 2px;
+}
+
+.choiceButton:active,
+.outcomeButton:active {
+  transform: scale(0.99);
+}
+
+/* Slight visual distinction for outcomes */
+.outcomeButton {
+  border-style: dashed;
+  background: var(--branch-bg);
+}
+
+.outcomeButton:hover {
+  border-style: solid;
+}
+
+/* ---- Ending ---- */
+.endingMessage {
+  margin: 1.5rem 0 0;
+  padding: 1rem 1.25rem;
+  font-size: 0.9375rem;
+  font-weight: 500;
+  color: var(--branch-accent);
+  background: var(--branch-bg);
+  border-radius: var(--branch-radius);
+  text-align: center;
+}
+
+/* ---- Error ---- */
+.error {
+  margin: 0;
+  padding: 1rem;
+  color: #b91c1c;
+  background: #fef2f2;
+  border-radius: var(--branch-radius);
+}

package/DragAndDropActivity/README.md

@@ -38,7 +38,7 @@ DragAndDropActivity/
 
 ## Functionality
 
-- **Two columns**: Left column shows draggable items (shuffled), right column shows drop targets.
+- **Top and bottom**: Items are shown at the top (shuffled, in a row); drop target buckets are shown at the bottom. Users drag items down into the correct bucket.
 - **Drag and drop**: Users drag items and drop them on targets. Uses interact.js for robust pointer and touch support.
 - **Correct match**: When an item is dropped on a target whose `accepts` array includes that item's ID, the item snaps into place and becomes non-draggable. The target shows a green border and success background.
 - **Incorrect match**: When dropped on a wrong target, the item animates back to its original position via a CSS transform transition, and the target briefly shows a red border.

package/DragAndDropActivity/index.tsx

@@ -234,13 +234,13 @@ const DragAndDropActivity: React.FC<DragAndDropProps> = ({
       aria-label="Drag and drop quiz activity"
     >
       <p className={styles.instruction}>
-        Drag each item to its correct drop target. Items will snap into place
-        when correctly matched.
+        Drag each item down into the correct target bucket. Items will snap into
+        place when correctly matched.
       </p>
 
       <div className={styles.layout}>
         <section
-          className={styles.column}
+          className={`${styles.column} ${styles.itemsArea}`}
           aria-label="Items to place"
         >
           <h3 className={styles.columnTitle}>Items</h3>
@@ -278,10 +278,10 @@ const DragAndDropActivity: React.FC<DragAndDropProps> = ({
         </section>
 
         <section
-          className={styles.column}
+          className={`${styles.column} ${styles.targetsArea}`}
           aria-label="Drop targets"
         >
-          <h3 className={styles.columnTitle}>Targets</h3>
+          <h3 className={styles.columnTitle}>Target buckets</h3>
           <ul className={styles.list} role="list">
             {targets.map((target) => {
               const placedItemId = placements.get(target.id);