@zomako/elearning-components 2.0.7 → 2.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zomako/elearning-components",
-  "version": "2.0.7",
+  "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/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.

package/src/components/ResponsiveWrapper/index.tsx

@@ -0,0 +1,84 @@
+import React, { useRef, useState, useEffect } from 'react';
+import styles from './style.module.css';
+
+export interface ResponsiveWrapperProps {
+  children: React.ReactNode;
+  /** Optional max-width for the container (default: "100%") */
+  maxWidth?: string;
+  /** Optional padding (default: "1rem") */
+  padding?: string;
+  /** Optional gap between grid rows (default: "1rem") */
+  gap?: string;
+}
+
+const MOBILE_BREAKPOINT_PX = 600;
+
+/**
+ * ResponsiveWrapper – A responsive layout container using CSS Grid with three rows
+ * (header, body, footer). The body section is scrollable when content exceeds the
+ * viewport. Uses ResizeObserver for dimension-based styling and 100dvh for
+ * mobile viewport handling.
+ */
+const ResponsiveWrapper: React.FC<ResponsiveWrapperProps> = ({
+  children,
+  maxWidth = '100%',
+  padding = '1rem',
+  gap = '1rem',
+}) => {
+  const containerRef = useRef<HTMLSectionElement>(null);
+  const [isMobile, setIsMobile] = useState(false);
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+
+    // ResizeObserver tracks the container's width so we can apply mobile vs desktop
+    // styles based on actual rendered size (e.g. in responsive design mode or
+    // when the container is constrained by a parent), not just the viewport.
+    const resizeObserver = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const width = entry.contentRect.width;
+        setIsMobile(width < MOBILE_BREAKPOINT_PX);
+      }
+    });
+
+    resizeObserver.observe(el);
+
+    // Set initial value in case ResizeObserver fires after first paint
+    setIsMobile(el.getBoundingClientRect().width < MOBILE_BREAKPOINT_PX);
+
+    return () => {
+      resizeObserver.disconnect();
+    };
+  }, []);
+
+  return (
+    <section
+      ref={containerRef}
+      className={`${styles.wrapper} ${isMobile ? styles.mobile : styles.desktop}`}
+      style={{
+        maxWidth,
+        padding,
+        gap,
+      }}
+      role="region"
+      aria-label="Content wrapper"
+    >
+      <header className={styles.header} aria-hidden>
+        {/* Optional header slot; empty by default. Structure supports future extension. */}
+      </header>
+      <main
+        className={styles.body}
+        tabIndex={0}
+        aria-label="Main content"
+      >
+        {children}
+      </main>
+      <footer className={styles.footer} aria-hidden>
+        {/* Optional footer slot; empty by default. */}
+      </footer>
+    </section>
+  );
+};
+
+export default ResponsiveWrapper;

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

@@ -0,0 +1,73 @@
+/* Three-row grid: header (auto), body (1fr), footer (auto). Body scrolls when content overflows. */
+.wrapper {
+  display: grid;
+  grid-template-rows: auto 1fr auto;
+  min-height: 0;
+  /* 100dvh: dynamic viewport height – accounts for mobile browser UI (address bar) showing/hiding */
+  height: 100dvh;
+  max-height: 100dvh;
+  box-sizing: border-box;
+  font-size: clamp(14px, 2.5vw, 18px);
+  line-height: 1.5;
+  color: #1a1a1a;
+  background-color: #ffffff;
+}
+
+.header,
+.footer {
+  min-height: 0;
+  flex-shrink: 0;
+}
+
+/* Scrollable body: takes remaining space and scrolls when content exceeds viewport */
+.body {
+  min-height: 0;
+  overflow-y: auto;
+  overflow-x: hidden;
+  padding: clamp(0.5rem, 2vw, 1.5rem);
+  -webkit-overflow-scrolling: touch;
+}
+
+.body:focus {
+  outline: none;
+}
+
+.body:focus-visible {
+  outline: 2px solid #2563eb;
+  outline-offset: 2px;
+}
+
+/* Ensure readable text and sufficient touch targets on mobile */
+.mobile .body {
+  padding: clamp(0.5rem, 2vw, 1.5rem);
+  font-size: clamp(14px, 2.5vw, 16px);
+}
+
+/* Minimum 44px touch targets for mobile accessibility (WCAG 2.5.5) */
+.mobile .body button,
+.mobile .body a[href],
+.mobile .body [role="button"] {
+  min-height: 44px;
+  min-width: 44px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* Desktop: more spacing and typography */
+.desktop .body {
+  padding: clamp(0.5rem, 2vw, 1.5rem);
+}
+
+/* Media query fallback for environments where ResizeObserver might not drive class */
+@media (max-width: 599px) {
+  .wrapper {
+    font-size: clamp(14px, 2.5vw, 16px);
+  }
+}
+
+@media (min-width: 600px) {
+  .wrapper {
+    font-size: clamp(14px, 2.5vw, 18px);
+  }
+}

package/src/index.ts

@@ -22,4 +22,15 @@ export {
   type DraggableItem,
   type DropTarget,
   type DragAndDropProps,
-} from '../DragAndDropActivity';
+} from '../DragAndDropActivity';
+export {
+  default as BranchingScenario,
+  type BranchingScenarioProps,
+  type ScenarioNode,
+  type Choice,
+  type Outcome,
+} from '../BranchingScenario';
+export {
+  default as ResponsiveWrapper,
+  type ResponsiveWrapperProps,
+} from './components/ResponsiveWrapper';