@zomako/elearning-components 2.0.6 → 2.0.8

package/package.json

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

package/src/App.jsx

@@ -6,6 +6,7 @@ import {
   MatchingActivity,
   SortingActivity,
   DragAndDropActivity,
+  BranchingScenario,
 } from './index';
 
 const accordionItems = [
@@ -58,6 +59,70 @@ const dragDropTargets = [
   { id: 'target-es', accepts: ['madrid'], label: 'Capital of Spain' },
 ];
 
+const branchingNodes = {
+  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',
+        outcomes: [
+          {
+            id: 'friend',
+            text: 'You find a lost traveler. You gain a companion.',
+            nextNodeId: 'ending-friend',
+            scoreModifier: 10,
+            variableUpdates: { companion: true },
+          },
+          {
+            id: 'wolf',
+            text: 'A wolf appears. You retreat safely.',
+            nextNodeId: 'ending-forest',
+            scoreModifier: 0,
+          },
+        ],
+      },
+      { id: 'back', 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-friend': {
+    id: 'ending-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: [],
+  },
+};
+
 export default function App() {
   return (
     <div style={{ padding: '2rem', maxWidth: 800, margin: '0 auto' }}>
@@ -96,7 +161,7 @@ export default function App() {
         />
       </section>
 
-      <section>
+      <section style={{ marginBottom: '2.5rem' }}>
         <h2>DragAndDropActivity</h2>
         <DragAndDropActivity
           items={dragDropItems}
@@ -104,6 +169,15 @@ export default function App() {
           onComplete={(result) => console.log('Drag and drop result:', result)}
         />
       </section>
+
+      <section>
+        <h2>BranchingScenario</h2>
+        <BranchingScenario
+          nodes={branchingNodes}
+          startNodeId="start"
+          onComplete={(result) => console.log('Branching scenario complete:', result)}
+        />
+      </section>
     </div>
   );
 }

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;
+}

package/src/components/ResponsiveWrapper/README.md

@@ -0,0 +1,126 @@
+# ResponsiveWrapper
+
+A responsive layout container component that uses **CSS Grid** to provide a three-row structure (header, body, footer) with a scrollable body section. It uses **ResizeObserver** for dimension-based styling and **100dvh** for reliable viewport height on mobile browsers.
+
+## Purpose
+
+ResponsiveWrapper is designed to:
+
+- Provide a consistent, responsive layout for eLearning and web content that works across screen sizes.
+- Keep the main content area scrollable when it exceeds the viewport, while preserving a fixed header/footer structure.
+- Adapt styling for mobile (< 600px) vs desktop (≥ 600px) using both **media queries** and **ResizeObserver** (so behavior is correct when the component is inside a constrained container, e.g. in an iframe or split view).
+- Use **fluid typography and spacing** via `clamp()` so text and padding scale smoothly without separate breakpoints.
+- Use **100dvh** (dynamic viewport height) so layout behaves correctly when mobile browser chrome (e.g. address bar) shows or hides.
+
+## Props
+
+| Prop       | Type             | Default   | Description                                                |
+| ---------- | ---------------- | --------- | ---------------------------------------------------------- |
+| `children` | `React.ReactNode`| *required*| Content rendered inside the scrollable body section.       |
+| `maxWidth` | `string`         | `"100%"`  | Optional max-width for the wrapper container.              |
+| `padding`  | `string`         | `"1rem"`  | Optional padding applied to the wrapper.                   |
+| `gap`      | `string`         | `"1rem"`  | Optional gap between grid rows (header, body, footer).     |
+
+### TypeScript interface
+
+```ts
+interface ResponsiveWrapperProps {
+  children: React.ReactNode;
+  maxWidth?: string;  // default: "100%"
+  padding?: string;   // default: "1rem"
+  gap?: string;       // default: "1rem"
+}
+```
+
+## Usage
+
+### Basic
+
+Wrap any content in the scrollable body:
+
+```tsx
+import { ResponsiveWrapper } from '@zomako/elearning-components';
+
+function App() {
+  return (
+    <ResponsiveWrapper>
+      <p>Your main content here. This area will scroll if it exceeds the viewport.</p>
+    </ResponsiveWrapper>
+  );
+}
+```
+
+### With custom layout options
+
+```tsx
+<ResponsiveWrapper
+  maxWidth="720px"
+  padding="1.5rem"
+  gap="1.25rem"
+>
+  <article>
+    <h1>Lesson title</h1>
+    <p>Long content…</p>
+  </article>
+</ResponsiveWrapper>
+```
+
+### Wrapping other components
+
+```tsx
+<ResponsiveWrapper maxWidth="min(90vw, 800px)">
+  <Accordion items={items} />
+</ResponsiveWrapper>
+```
+
+## Responsive behavior
+
+- **Viewport height**: The wrapper uses `height: 100dvh` and `max-height: 100dvh` so it fills the dynamic viewport and adapts when the mobile browser UI (e.g. address bar) appears or disappears.
+- **Width-based styling**: A **ResizeObserver** watches the wrapper’s width. When width is **&lt; 600px**, the component gets mobile-optimized styles (e.g. larger touch targets, adjusted typography). When width is **≥ 600px**, desktop styles apply. This works even when the component is inside a constrained parent (e.g. iframe or responsive design tools), not only the window.
+- **Media queries**: CSS also uses `@media (max-width: 599px)` and `@media (min-width: 600px)` so that layout and typography remain correct if JavaScript is slow or ResizeObserver is unavailable.
+
+## CSS Grid layout structure
+
+The layout is a single grid with three rows:
+
+- **Row 1 (header)**: `grid-template-rows: auto` — height by content (currently empty; structure is in place for future header content).
+- **Row 2 (body)**: `1fr` — takes all remaining space; this is the scrollable area where `children` are rendered.
+- **Row 3 (footer)**: `auto` — height by content (currently empty).
+
+The body cell uses `min-height: 0` so the grid allows it to shrink, and `overflow-y: auto` so content scrolls when it exceeds the available height.
+
+## Fluid sizing with `clamp()`
+
+- **Padding (body)**: `padding: clamp(0.5rem, 2vw, 1.5rem)` — scales between 0.5rem and 1.5rem with viewport.
+- **Font size**: `font-size: clamp(14px, 2.5vw, 18px)` (desktop) and a slightly smaller max on mobile so text stays readable at all sizes.
+
+This reduces the need for many breakpoint-specific values and keeps scaling smooth.
+
+## Mobile-first and accessibility
+
+- **Mobile-first**: Base styles work for small screens; desktop styles enhance layout and typography at 600px and up. ResizeObserver aligns behavior with the actual container width.
+- **Semantic HTML**: Uses `<section>`, `<header>`, `<main>`, and `<footer>` for structure and assistive tech.
+- **Keyboard**: The main content area is focusable (`tabIndex={0}`) and has a visible `:focus-visible` outline.
+- **ARIA**: The wrapper has `role="region"` and `aria-label="Content wrapper"`; the main area has `aria-label="Main content"`. Header and footer are `aria-hidden` when empty.
+- **Touch targets**: On mobile, buttons and link-like elements inside the body get a minimum size of 44×44px where possible to improve tap usability and align with WCAG 2.5.5 (Target Size).
+- **Contrast**: Text and background use high-contrast defaults; override via your own styles if needed.
+
+## Dependencies
+
+- **React** (with hooks: `useRef`, `useState`, `useEffect`).
+- **ResizeObserver** (built-in in modern browsers; no extra library).
+- **CSS**: Grid, Flexbox, media queries, and `clamp()` — no JS-based styling required.
+
+## File structure
+
+```
+ResponsiveWrapper/
+  index.tsx         – Main component and ResizeObserver logic
+  style.module.css  – Scoped styles (Grid, clamp, media queries)
+  README.md         – This documentation
+```
+
+## Browser support
+
+- Modern browsers that support CSS Grid, `clamp()`, and `ResizeObserver`.
+- `100dvh` is supported in current Chrome, Safari, and Firefox; consider a fallback (e.g. `height: 100vh`) for very old browsers if needed.