@zomako/elearning-components 2.0.4 → 2.0.6

package/Accordion/README.md

@@ -0,0 +1,74 @@
+# Accordion
+
+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.
+
+## File structure
+
+```
+Accordion/
+├── index.tsx         # Component and TypeScript interfaces
+├── style.module.css  # Component styles (pure CSS animations)
+└── README.md         # This file
+```
+
+## Props
+
+### `AccordionProps`
+
+| 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. |
+
+## Usage example
+
+```tsx
+import Accordion, { AccordionItem } from './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.',
+  },
+];
+
+function FAQ() {
+  return <Accordion items={items} />;
+}
+```
+
+### Multiple panels open
+
+```tsx
+<Accordion
+  items={items}
+  allowMultiple
+  defaultOpenId={['included', 'support']}
+/>
+```
+
+### One panel open by default
+
+```tsx
+<Accordion items={items} defaultOpenId="refund" />
+```
+
+## Accessibility
+
+- **Keyboard**: Enter or Space toggles the panel. Arrow keys move focus between headers. Home/End focus first/last.
+- **ARIA**: Correct `aria-expanded`, `aria-controls`, `aria-labelledby`, and `aria-hidden` for screen readers.

package/DragAndDropActivity/README.md

@@ -0,0 +1,124 @@
+# DragAndDropActivity
+
+A highly interactive and accessible React drag-and-drop quiz component. Users drag items from a source list to drop targets; correct matches snap into place, incorrect drops animate back to the source. Built with **interact.js** for drag-and-drop logic and **pure CSS** for transitions and transforms.
+
+## File structure
+
+```
+DragAndDropActivity/
+├── index.tsx         # Component, types, and exports
+├── style.module.css  # CSS Modules styles
+└── README.md         # This file
+```
+
+## Props
+
+### `DragAndDropProps`
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `items` | `DraggableItem[]` | Yes | Draggable items. Each has an `id` and `content` (text or HTML). |
+| `targets` | `DropTarget[]` | Yes | Drop targets. Each has an `id`, `accepts` (array of correct item IDs), and `label`. |
+| `onComplete` | `(result: { score: number; correct: number; total: number }) => void` | Yes | Callback invoked when all items are correctly placed. Receives `score` (0–100), `correct` count, and `total` count. |
+
+### `DraggableItem`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique identifier for the draggable item. |
+| `content` | `string` | Text or HTML content displayed on the item. |
+
+### `DropTarget`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique identifier for the drop target. |
+| `accepts` | `string[]` | Array of `DraggableItem.id` values that are correct for this target. A target can accept multiple items or a single item. |
+| `label` | `string` | Text or HTML content displayed as the target label. |
+
+## Functionality
+
+- **Two columns**: Left column shows draggable items (shuffled), right column shows drop targets.
+- **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.
+- **Visual feedback**:
+  - Drop targets highlight (accent border and background) when a draggable is over them.
+  - Correct drops: green border and success styling.
+  - Incorrect drops: red border and error styling during snap-back.
+- **Completion**: When every target has its correct item(s) placed (based on the `accepts` arrays), `onComplete` is called once with `{ score, correct, total }`.
+
+## Styling and animations
+
+- **CSS Modules**: All styles are in `style.module.css` with scoped class names.
+- **Transitions**: Items and targets use CSS transitions for border, background, transform, and box-shadow.
+- **Snap-back**: Incorrect drops trigger a 0.4s `ease-out` transform transition to return the item to its source position.
+- **Correct match**: Targets use a short scale + box-shadow keyframe animation for feedback.
+
+## Usage example
+
+```tsx
+import React from 'react';
+import DragAndDropActivity, {
+  type DraggableItem,
+  type DropTarget,
+  type DragAndDropProps,
+} from './DragAndDropActivity';
+
+const items: DraggableItem[] = [
+  { id: 'paris', content: 'Paris' },
+  { id: 'berlin', content: 'Berlin' },
+  { id: 'madrid', content: 'Madrid' },
+];
+
+const targets: DropTarget[] = [
+  { id: 'target-fr', accepts: ['paris'], label: 'Capital of France' },
+  { id: 'target-de', accepts: ['berlin'], label: 'Capital of Germany' },
+  { id: 'target-es', accepts: ['madrid'], label: 'Capital of Spain' },
+];
+
+function App() {
+  const handleComplete: DragAndDropProps['onComplete'] = (result) => {
+    console.log('Score:', result.score);
+    console.log('Correct:', result.correct, 'of', result.total);
+  };
+
+  return (
+    <div style={{ padding: '2rem', maxWidth: 700 }}>
+      <DragAndDropActivity
+        items={items}
+        targets={targets}
+        onComplete={handleComplete}
+      />
+    </div>
+  );
+}
+```
+
+### Example with HTML content
+
+```tsx
+const items: DraggableItem[] = [
+  { id: 'x', content: '<strong>x</strong>' },
+  { id: 'y', content: '<em>y</em>' },
+];
+
+const targets: DropTarget[] = [
+  { id: 'var1', accepts: ['x'], label: 'First variable' },
+  { id: 'var2', accepts: ['y'], label: 'Second variable' },
+];
+```
+
+**Note:** Use `dangerouslySetInnerHTML` only with trusted, sanitized content.
+
+## Dependencies
+
+- **React** 18.x
+- **interactjs** (interact.js)
+
+## Accessibility
+
+- Regions and sections use `role="region"` and `aria-label`.
+- Items use `aria-label` and `tabIndex` for focus management.
+- Drop targets use `aria-label` and `role="group"`.
+- Content is exposed to assistive technologies; ensure `content` and `label` values are meaningful for screen readers.

package/DragAndDropActivity/index.tsx

@@ -0,0 +1,343 @@
+import React, {
+  useState,
+  useCallback,
+  useEffect,
+  useRef,
+  useMemo,
+} from 'react';
+import interact from 'interactjs';
+import styles from './style.module.css';
+
+export interface DraggableItem {
+  id: string;
+  content: string;
+}
+
+export interface DropTarget {
+  id: string;
+  accepts: string[];
+  label: string;
+}
+
+export interface DragAndDropProps {
+  items: DraggableItem[];
+  targets: DropTarget[];
+  onComplete: (result: {
+    score: number;
+    correct: number;
+    total: number;
+  }) => void;
+}
+
+function shuffleArray<T>(array: T[]): T[] {
+  const shuffled = [...array];
+  for (let i = shuffled.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+  }
+  return shuffled;
+}
+
+const DragAndDropActivity: React.FC<DragAndDropProps> = ({
+  items,
+  targets,
+  onComplete,
+}) => {
+  const [shuffledItems] = useState(() => shuffleArray(items));
+  const [placements, setPlacements] = useState<Map<string, string>>(new Map());
+  const [snapBackItemId, setSnapBackItemId] = useState<string | null>(null);
+  const [incorrectTargetId, setIncorrectTargetId] = useState<string | null>(
+    null
+  );
+  const [targetHoverId, setTargetHoverId] = useState<string | null>(null);
+  const [targetFeedback, setTargetFeedback] = useState<
+    Map<string, 'correct' | 'incorrect' | null>
+  >(new Map());
+  const [hasCompleted, setHasCompleted] = useState(false);
+
+  const itemPositions = useRef<Map<string, { x: number; y: number }>>(
+    new Map()
+  );
+  const itemRefs = useRef<Map<string, HTMLDivElement | null>>(new Map());
+  const targetRefs = useRef<Map<string, HTMLDivElement | null>>(new Map());
+  const interactables = useRef<{ unset: () => void }[]>([]);
+
+  const unplacedItems = useMemo(
+    () =>
+      shuffledItems.filter(
+        (item) => ![...placements.values()].includes(item.id)
+      ),
+    [shuffledItems, placements]
+  );
+
+  const targetById = useMemo(() => {
+    const map = new Map<string, DropTarget>();
+    targets.forEach((t) => map.set(t.id, t));
+    return map;
+  }, [targets]);
+
+  useEffect(() => {
+    if (
+      placements.size === targets.length &&
+      placements.size > 0 &&
+      !hasCompleted
+    ) {
+      setHasCompleted(true);
+      const correct = placements.size;
+      const total = targets.length;
+      const score = total > 0 ? Math.round((correct / total) * 100) : 0;
+      onComplete({ score, correct, total });
+    }
+  }, [placements.size, targets.length, hasCompleted, onComplete]);
+
+  const handleSnapBackEnd = useCallback((targetIdToClear?: string) => {
+    setSnapBackItemId(null);
+    setTargetFeedback((prev) => {
+      if (targetIdToClear) {
+        const next = new Map(prev);
+        next.delete(targetIdToClear);
+        return next;
+      }
+      return prev;
+    });
+    setIncorrectTargetId(null);
+  }, []);
+
+  const handleDrop = useCallback(
+    (event: { relatedTarget: Element; target: Element }) => {
+      const draggableEl = event.relatedTarget;
+      const dropzoneEl = event.target;
+      const itemId = draggableEl.getAttribute('data-item-id');
+      const targetId = dropzoneEl.getAttribute('data-target-id');
+      if (!itemId || !targetId) return;
+
+      const target = targetById.get(targetId);
+      if (!target || placements.has(targetId)) return;
+
+      const isCorrect = target.accepts.includes(itemId);
+
+      if (isCorrect) {
+        itemPositions.current.set(itemId, { x: 0, y: 0 });
+        setPlacements((prev) => {
+          const next = new Map(prev).set(targetId, itemId);
+          return next;
+        });
+        setTargetFeedback((prev) => new Map(prev).set(targetId, 'correct'));
+      } else {
+        setTargetFeedback((prev) => new Map(prev).set(targetId, 'incorrect'));
+        setSnapBackItemId(itemId);
+        setIncorrectTargetId(targetId);
+      }
+    },
+    [targetById, placements]
+  );
+
+  useEffect(() => {
+    const cleanups: (() => void)[] = [];
+
+    unplacedItems.forEach((item) => {
+      const el = itemRefs.current.get(item.id);
+      const isPlaced = [...placements.values()].includes(item.id);
+      if (!el || isPlaced) return;
+
+      const pos = itemPositions.current.get(item.id) ?? { x: 0, y: 0 };
+      itemPositions.current.set(item.id, pos);
+
+      const interactable = interact(el)
+        .draggable({
+          inertia: false,
+          listeners: {
+            move(event) {
+              if (snapBackItemId === item.id) return;
+              pos.x += event.dx;
+              pos.y += event.dy;
+              el.style.transform = `translate(${pos.x}px, ${pos.y}px)`;
+            },
+          },
+        })
+        .styleCursor(false);
+
+      interactables.current.push(interactable);
+
+      cleanups.push(() => {
+        interactable.unset();
+      });
+    });
+
+    targets.forEach((target) => {
+      const el = targetRefs.current.get(target.id);
+      if (!el) return;
+
+      const interactable = interact(el).dropzone({
+        accept: '[data-item-id]',
+        overlap: 0.5,
+        ondropactivate: () => {
+          setTargetHoverId(target.id);
+        },
+        ondragenter: () => {
+          setTargetHoverId(target.id);
+        },
+        ondragleave: () => {
+          setTargetHoverId(null);
+        },
+        ondropdeactivate: () => {
+          setTargetHoverId(null);
+        },
+        ondrop: (event: { relatedTarget: Element; target: Element }) => {
+          handleDrop(event);
+        },
+      });
+
+      interactables.current.push(interactable);
+      cleanups.push(() => interactable.unset());
+    });
+
+    return () => {
+      cleanups.forEach((fn) => fn());
+      interactables.current = [];
+    };
+  }, [unplacedItems, placements, targets, handleDrop, snapBackItemId]);
+
+  useEffect(() => {
+    if (snapBackItemId) {
+      const el = itemRefs.current.get(snapBackItemId);
+      const targetIdToClear = incorrectTargetId;
+      if (el) {
+        itemPositions.current.set(snapBackItemId, { x: 0, y: 0 });
+        el.style.transition = 'transform 0.4s ease-out';
+        el.style.transform = 'translate(0, 0)';
+        const onTransitionEnd = () => {
+          el.style.transition = '';
+          handleSnapBackEnd(targetIdToClear ?? undefined);
+          el.removeEventListener('transitionend', onTransitionEnd);
+        };
+        el.addEventListener('transitionend', onTransitionEnd);
+        return () => el.removeEventListener('transitionend', onTransitionEnd);
+      } else {
+        handleSnapBackEnd(targetIdToClear ?? undefined);
+      }
+    }
+  }, [snapBackItemId, incorrectTargetId, handleSnapBackEnd]);
+
+  if (!items.length || !targets.length) {
+    return (
+      <div className={styles.wrapper} role="region" aria-label="Drag and drop activity">
+        <p className={styles.empty}>No items or targets to place.</p>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={styles.wrapper}
+      role="region"
+      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.
+      </p>
+
+      <div className={styles.layout}>
+        <section
+          className={styles.column}
+          aria-label="Items to place"
+        >
+          <h3 className={styles.columnTitle}>Items</h3>
+          <ul className={styles.list} role="list">
+            {unplacedItems.map((item) => (
+              <li key={item.id} className={styles.listItem}>
+                <div
+                  ref={(node) => itemRefs.current.set(item.id, node)}
+                  data-item-id={item.id}
+                  className={`${styles.item} ${
+                    snapBackItemId === item.id ? styles.itemSnapBack : ''
+                  }`}
+                  draggable={false}
+                  aria-label={`Draggable item: ${item.content}`}
+                  tabIndex={hasCompleted ? -1 : 0}
+                  style={{
+                    transform:
+                      snapBackItemId !== item.id
+                        ? `translate(${
+                            itemPositions.current.get(item.id)?.x ?? 0
+                          }px, ${
+                            itemPositions.current.get(item.id)?.y ?? 0
+                          }px)`
+                        : undefined,
+                  }}
+                >
+                  <span
+                    className={styles.itemContent}
+                    dangerouslySetInnerHTML={{ __html: item.content }}
+                  />
+                </div>
+              </li>
+            ))}
+          </ul>
+        </section>
+
+        <section
+          className={styles.column}
+          aria-label="Drop targets"
+        >
+          <h3 className={styles.columnTitle}>Targets</h3>
+          <ul className={styles.list} role="list">
+            {targets.map((target) => {
+              const placedItemId = placements.get(target.id);
+              const feedback = targetFeedback.get(target.id);
+              const isOver = targetHoverId === target.id;
+              const isFilled = !!placedItemId;
+              const placedItem = placedItemId
+                ? shuffledItems.find((i) => i.id === placedItemId)
+                : null;
+
+              return (
+                <li key={target.id} className={styles.listItem}>
+                  <div
+                    ref={(node) => targetRefs.current.set(target.id, node)}
+                    data-target-id={target.id}
+                    className={`${styles.target} ${
+                      isOver && !isFilled ? styles.targetOver : ''
+                    } ${
+                      feedback === 'correct'
+                        ? styles.targetCorrect
+                        : feedback === 'incorrect'
+                          ? styles.targetIncorrect
+                          : ''
+                    } ${isFilled ? styles.targetFilled : ''}`}
+                    aria-label={`Drop target: ${target.label}${placedItemId ? `, contains ${placedItem?.content}` : ', empty'}`}
+                    role="group"
+                  >
+                    <span
+                      className={styles.targetLabel}
+                      dangerouslySetInnerHTML={{ __html: target.label }}
+                    />
+                    {placedItem ? (
+                      <span
+                        className={styles.placedContent}
+                        dangerouslySetInnerHTML={{
+                          __html: placedItem.content,
+                        }}
+                        aria-hidden="true"
+                      />
+                    ) : (
+                      <span
+                        className={styles.targetPlaceholder}
+                        aria-hidden="true"
+                      >
+                        Drop here
+                      </span>
+                    )}
+                  </div>
+                </li>
+              );
+            })}
+          </ul>
+        </section>
+      </div>
+    </div>
+  );
+};
+
+export default DragAndDropActivity;