@zomako/elearning-components 2.0.6 → 2.0.7

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/README.md

@@ -28,6 +28,10 @@ A drag-and-drop matching activity where users match items from one column to the
 
 A highly interactive drag-and-drop quiz where users drag items to drop targets. Correct matches snap into place; incorrect drops animate back to the source. Uses interact.js and pure CSS animations. See `DragAndDropActivity/README.md` for detailed documentation.
 
+### BranchingScenario
+
+A choose-your-own-path scenario component. Renders narrative nodes with choices and outcomes, tracks path/score/variables, and supports conditional choices. Uses pure CSS for fade and slide transitions. See `BranchingScenario/README.md` for detailed documentation.
+
 ## Getting Started
 
 ### Installation
@@ -78,6 +82,10 @@ elearning-components/
 │   ├── index.tsx           # Component and exports
 │   ├── style.module.css    # CSS Modules styles
 │   └── README.md           # Documentation
+├── BranchingScenario/      # BranchingScenario component
+│   ├── index.tsx           # Component and exports
+│   ├── style.module.css    # CSS Modules styles
+│   └── README.md           # Documentation
 ├── src/                    # Application source
 │   ├── App.jsx             # Demo app
 │   └── main.jsx            # Entry point

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zomako/elearning-components",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "A library of interactive and SCORM-compliant eLearning components.",
   "main": "dist/index.js",
   "scripts": {

package/src/components/Accordion/README.md

@@ -0,0 +1,164 @@
+# Accordion Component
+
+A fully accessible React accordion using **pure CSS** for animations and CSS Modules for styling. It renders a list of collapsible items with smooth expand/collapse and supports either single or multiple open panels. No Framer Motion or other animation library is required.
+
+## Purpose
+
+The `Accordion` component is designed for e-learning and content-heavy UIs where you need to reveal content on demand without leaving the page. Use it for FAQs, course modules, step-by-step instructions, or any list of titled sections with collapsible bodies.
+
+## Features
+
+- **Pure CSS expand/collapse** – Smooth animations without Framer Motion; consistent with a CSS-first approach and smaller bundle size
+- **Single or multiple open panels** – Controlled by the `allowMultiple` prop
+- **Id-based API** – Items use required `id`; initial open state is set via `defaultOpenId` (string or string[])
+- **Keyboard accessible** – Enter/Space to toggle, Arrow keys to move focus, Home/End for first/last
+- **ARIA-compliant** – Correct `aria-expanded`, `aria-controls`, `aria-labelledby`, and `aria-hidden` for screen readers
+- **Clean, modern styling** – CSS Modules with a clear header/content distinction
+- **TypeScript** – Exported `AccordionProps` and `AccordionItem` interfaces
+
+## Installation
+
+### Prerequisites
+
+- React 16.8+ (hooks)
+- Node.js and npm (or yarn/pnpm)
+
+### Dependencies
+
+```bash
+npm install react react-dom
+```
+
+No animation library is required.
+
+## Props
+
+The component accepts props as defined in the `AccordionProps` interface.
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `items` | `AccordionItem[]` | Yes | — | List of accordion items. Each must have `id`, `title`, and `content`. |
+| `allowMultiple` | `boolean` | No | `false` | If `true`, multiple panels can be open at once. If `false`, opening one closes the others. |
+| `defaultOpenId` | `string \| string[]` | No | — | Id(s) of item(s) to open initially. Single string or array of strings. |
+
+### AccordionItem
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | Yes | Unique id for the item (used for state and as React `key`). |
+| `title` | `string` | Yes | Label for the accordion header. |
+| `content` | `React.ReactNode` | Yes | Content shown when the panel is expanded. |
+
+### TypeScript interfaces
+
+```typescript
+import Accordion, { AccordionProps, AccordionItem } from './Accordion';
+
+interface AccordionItem {
+  id: string;
+  title: string;
+  content: React.ReactNode;
+}
+
+interface AccordionProps {
+  items: AccordionItem[];
+  allowMultiple?: boolean;
+  defaultOpenId?: string | string[];
+}
+```
+
+## Usage
+
+### Basic example (single open panel)
+
+Only one panel is open at a time. No panel is open initially.
+
+```tsx
+import Accordion, { AccordionItem } from './components/Accordion';
+
+const items: AccordionItem[] = [
+  {
+    id: 'included',
+    title: 'What is included?',
+    content: 'Access to all lessons, quizzes, and downloadable resources for 12 months.',
+  },
+  {
+    id: 'refund',
+    title: 'Can I get a refund?',
+    content: 'Yes. You can request a full refund within 14 days of purchase if you have not completed more than 2 lessons.',
+  },
+  {
+    id: 'support',
+    title: 'How do I get support?',
+    content: 'Use the Help button in the course dashboard or email support@example.com.',
+  },
+];
+
+function FAQ() {
+  return <Accordion items={items} />;
+}
+```
+
+### Multiple panels open
+
+Allow several panels to be open at once, with specific items open by id:
+
+```tsx
+<Accordion
+  items={items}
+  allowMultiple
+  defaultOpenId={['included', 'support']}
+/>
+```
+
+### One panel open by default (single mode)
+
+Open a single item initially by id:
+
+```tsx
+<Accordion
+  items={items}
+  defaultOpenId="refund"
+/>
+```
+
+### Rich content
+
+`content` can be any `React.ReactNode` (e.g. lists, links, components):
+
+```tsx
+const items: AccordionItem[] = [
+  {
+    id: 'module-1',
+    title: 'Module 1: Introduction',
+    content: (
+      <>
+        <p>Welcome to the course. In this module you will:</p>
+        <ul>
+          <li>Learn the key concepts</li>
+          <li>Complete a short quiz</li>
+        </ul>
+      </>
+    ),
+  },
+];
+```
+
+## Accessibility
+
+- **Keyboard**: Each header is focusable. Enter or Space toggles the panel. Arrow Down/Right moves to the next header, Arrow Up/Left to the previous. Home focuses the first header, End the last.
+- **ARIA**: The root has `role="region"` and `aria-label="Accordion"`. Each trigger has `aria-expanded` and `aria-controls` pointing to its panel. Each panel has `role="region"`, `aria-labelledby` pointing to its header, and `aria-hidden` when collapsed.
+- **Focus**: Focus is not trapped; keyboard users can tab in and out of the accordion and use the arrow keys to move between headers.
+
+## Styling
+
+Styles are in `style.module.css`. Expand/collapse and chevron rotation use CSS transitions (no JavaScript animation library). You can override by targeting the accordion’s container in your own CSS. The design uses a light gray header background and white content area with a clear border between header and content.
+
+## File structure
+
+```
+Accordion/
+  index.tsx       # Component and TypeScript interfaces
+  style.module.css # Component styles (pure CSS animations)
+  README.md       # This file
+```

package/src/components/Accordion/index.tsx

@@ -0,0 +1,145 @@
+import React, { useState, useCallback, useId } from 'react';
+import styles from './style.module.css';
+
+export interface AccordionItem {
+  id: string;
+  title: string;
+  content: React.ReactNode;
+}
+
+export interface AccordionProps {
+  items: AccordionItem[];
+  allowMultiple?: boolean;
+  defaultOpenId?: string | string[];
+}
+
+function getInitialOpenSet(defaultOpenId?: string | string[]): Set<string> {
+  if (defaultOpenId == null) return new Set<string>();
+  if (typeof defaultOpenId === 'string') return new Set([defaultOpenId]);
+  return new Set(defaultOpenId);
+}
+
+const Accordion: React.FC<AccordionProps> = ({
+  items,
+  allowMultiple = false,
+  defaultOpenId,
+}) => {
+  const baseId = useId();
+  const [openSet, setOpenSet] = useState<Set<string>>(() => getInitialOpenSet(defaultOpenId));
+
+  const toggle = useCallback(
+    (id: string) => {
+      setOpenSet((prev) => {
+        const next = new Set(prev);
+        if (next.has(id)) {
+          next.delete(id);
+        } else {
+          if (!allowMultiple) next.clear();
+          next.add(id);
+        }
+        return next;
+      });
+    },
+    [allowMultiple]
+  );
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent, index: number) => {
+      const accordion = (e.currentTarget as HTMLElement).closest('[data-accordion]');
+      const triggers = accordion?.querySelectorAll<HTMLElement>('[data-accordion-trigger]');
+      if (!triggers?.length) return;
+
+      switch (e.key) {
+        case 'Enter':
+        case ' ':
+          e.preventDefault();
+          if (items[index]) toggle(items[index].id);
+          break;
+        case 'ArrowDown':
+        case 'ArrowRight':
+          e.preventDefault();
+          if (index < items.length - 1) triggers[index + 1]?.focus();
+          break;
+        case 'ArrowUp':
+        case 'ArrowLeft':
+          e.preventDefault();
+          if (index > 0) triggers[index - 1]?.focus();
+          break;
+        case 'Home':
+          e.preventDefault();
+          triggers[0]?.focus();
+          break;
+        case 'End':
+          e.preventDefault();
+          triggers[triggers.length - 1]?.focus();
+          break;
+        default:
+          break;
+      }
+    },
+    [items, toggle]
+  );
+
+  if (!items?.length) {
+    return (
+      <div className={styles.accordion} role="region" aria-label="Accordion">
+        <p className={styles.empty}>No items to display.</p>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={styles.accordion}
+      role="region"
+      aria-label="Accordion"
+      data-accordion
+    >
+      {items.map((item, index) => {
+        const isOpen = openSet.has(item.id);
+        const headerId = `${baseId}-header-${index}`;
+        const panelId = `${baseId}-panel-${index}`;
+
+        return (
+          <div
+            key={item.id}
+            className={styles.item}
+            data-open={isOpen}
+          >
+            <h3 className={styles.heading}>
+              <button
+                type="button"
+                id={headerId}
+                className={styles.trigger}
+                aria-expanded={isOpen}
+                aria-controls={panelId}
+                data-accordion-trigger
+                onClick={() => toggle(item.id)}
+                onKeyDown={(e) => handleKeyDown(e, index)}
+              >
+                <span className={styles.title}>{item.title}</span>
+                <span className={styles.icon} aria-hidden>
+                  ▼
+                </span>
+              </button>
+            </h3>
+            <div
+              id={panelId}
+              role="region"
+              aria-labelledby={headerId}
+              aria-hidden={!isOpen}
+              className={styles.panelWrapper}
+              data-open={isOpen}
+            >
+              <div className={styles.panel}>
+                <div className={styles.content}>{item.content}</div>
+              </div>
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+};
+
+export default Accordion;

package/src/components/Accordion/style.module.css

@@ -0,0 +1,123 @@
+.accordion {
+  width: 100%;
+  max-width: 640px;
+  margin: 0 auto;
+  font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+  color: #1a1a1a;
+}
+
+.empty {
+  padding: 1rem 0;
+  margin: 0;
+  color: #64748b;
+  font-size: 0.9375rem;
+}
+
+.item {
+  border: 1px solid #e2e8f0;
+  border-bottom: none;
+}
+
+.item:last-of-type {
+  border-bottom: 1px solid #e2e8f0;
+}
+
+.item:first-of-type {
+  border-radius: 8px 8px 0 0;
+}
+
+.item:last-of-type {
+  border-radius: 0 0 8px 8px;
+}
+
+.item:only-of-type {
+  border-radius: 8px;
+}
+
+.heading {
+  margin: 0;
+  font-size: 1rem;
+  font-weight: 600;
+}
+
+.trigger {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: 1rem 1.25rem;
+  background: #f8fafc;
+  border: none;
+  cursor: pointer;
+  text-align: left;
+  font-size: inherit;
+  font-weight: inherit;
+  color: inherit;
+  transition: background-color 0.2s ease;
+}
+
+.trigger:hover {
+  background: #f1f5f9;
+}
+
+.trigger:focus-visible {
+  outline: 2px solid #3b82f6;
+  outline-offset: 2px;
+}
+
+.item[data-open="true"] .trigger {
+  background: #fff;
+  border-bottom: 1px solid #e2e8f0;
+}
+
+.title {
+  flex: 1;
+  padding-right: 0.75rem;
+}
+
+.icon {
+  flex-shrink: 0;
+  font-size: 0.65rem;
+  color: #64748b;
+  transition: color 0.2s ease, transform 0.25s ease;
+}
+
+.trigger:hover .icon,
+.item[data-open="true"] .icon {
+  color: #3b82f6;
+}
+
+.item[data-open="true"] .icon {
+  transform: rotate(180deg);
+}
+
+.panelWrapper {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 0.25s ease-in-out;
+}
+
+.panelWrapper[data-open="true"] {
+  grid-template-rows: 1fr;
+}
+
+.panel {
+  min-height: 0;
+  overflow: hidden;
+}
+
+.content {
+  padding: 1rem 1.25rem 1.25rem;
+  background: #fff;
+  font-size: 0.9375rem;
+  line-height: 1.6;
+  color: #334155;
+}
+
+.content :first-child {
+  margin-top: 0;
+}
+
+.content :last-child {
+  margin-bottom: 0;
+}