@zomako/elearning-components 2.0.3 → 2.0.4

package/MatchingActivity/index.tsx

@@ -0,0 +1,208 @@
+import React, { useState, useCallback, useMemo } from 'react';
+import {
+  DndContext,
+  closestCenter,
+  PointerSensor,
+  useSensor,
+  useSensors,
+  DragEndEvent,
+  useDraggable,
+  useDroppable,
+} from '@dnd-kit/core';
+import styles from './style.module.css';
+
+export interface MatchItem {
+  id: string;
+  content: string;
+  matchId: string;
+}
+
+export interface MatchTarget {
+  id: string;
+  content: string;
+}
+
+export interface MatchingActivityProps {
+  items: MatchItem[];
+  targets: MatchTarget[];
+  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;
+}
+
+interface DraggableItemProps {
+  item: MatchItem;
+  disabled?: boolean;
+}
+
+function DraggableItem({ item, disabled }: DraggableItemProps) {
+  const { attributes, listeners, setNodeRef, transform, isDragging } = useDraggable({
+    id: item.id,
+    disabled,
+  });
+
+  const style: React.CSSProperties = transform
+    ? {
+        transform: `translate3d(${transform.x}px, ${transform.y}px, 0)`,
+      }
+    : undefined;
+
+  return (
+    <li
+      ref={setNodeRef}
+      style={style}
+      className={`${styles.item} ${isDragging ? styles.itemDragging : ''} ${disabled ? styles.itemDisabled : ''}`}
+      {...(disabled ? {} : { ...attributes, ...listeners })}
+    >
+      <span className={styles.itemContent}>{item.content}</span>
+    </li>
+  );
+}
+
+interface DroppableTargetProps {
+  target: MatchTarget;
+  matchedItem: MatchItem | null;
+  disabled?: boolean;
+}
+
+function DroppableTarget({ target, matchedItem, disabled }: DroppableTargetProps) {
+  const { setNodeRef, isOver } = useDroppable({
+    id: target.id,
+    disabled: disabled ?? !!matchedItem,
+  });
+
+  return (
+    <li
+      ref={setNodeRef}
+      className={`${styles.target} ${matchedItem ? styles.targetMatched : ''} ${isOver && !matchedItem ? styles.targetOver : ''}`}
+    >
+      <span className={styles.targetContent}>{target.content}</span>
+      {matchedItem ? (
+        <span className={styles.matchedContent}>{matchedItem.content}</span>
+      ) : (
+        <span className={styles.targetPlaceholder} aria-hidden="true">
+          Drop here
+        </span>
+      )}
+    </li>
+  );
+}
+
+const MatchingActivity: React.FC<MatchingActivityProps> = ({
+  items,
+  targets,
+  onComplete,
+}) => {
+  const [shuffledItems] = useState(() => shuffleArray(items));
+  const [shuffledTargets] = useState(() => shuffleArray(targets));
+  const [matchedTargetIds, setMatchedTargetIds] = useState<Set<string>>(new Set());
+  const [hasCompleted, setHasCompleted] = useState(false);
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, {
+      activationConstraint: { distance: 8 },
+    })
+  );
+
+  const itemsByMatchId = useMemo(() => {
+    const map = new Map<string, MatchItem>();
+    shuffledItems.forEach((i) => map.set(i.matchId, i));
+    return map;
+  }, [shuffledItems]);
+
+  const targetById = useMemo(() => {
+    const map = new Map<string, MatchTarget>();
+    shuffledTargets.forEach((t) => map.set(t.id, t));
+    return map;
+  }, [shuffledTargets]);
+
+  const unmatchedItems = useMemo(
+    () => shuffledItems.filter((item) => !matchedTargetIds.has(item.matchId)),
+    [shuffledItems, matchedTargetIds]
+  );
+
+  const handleDragEnd = useCallback(
+    (event: DragEndEvent) => {
+      const { active, over } = event;
+      if (!over || hasCompleted) return;
+
+      const targetId = String(over.id);
+      const item = shuffledItems.find((i) => i.id === active.id);
+      if (!item || !targetById.has(targetId)) return;
+      if (item.matchId !== targetId) return;
+      if (matchedTargetIds.has(targetId)) return;
+
+      const nextMatched = new Set(matchedTargetIds).add(targetId);
+      setMatchedTargetIds(nextMatched);
+
+      if (nextMatched.size === targets.length && !hasCompleted) {
+        setHasCompleted(true);
+        const correct = nextMatched.size;
+        const total = targets.length;
+        const score = total > 0 ? Math.round((correct / total) * 100) : 0;
+        onComplete({ score, correct, total });
+      }
+    },
+    [shuffledItems, targetById, matchedTargetIds, targets.length, hasCompleted, onComplete]
+  );
+
+  if (!items.length || !targets.length) {
+    return (
+      <div className={styles.wrapper}>
+        <p className={styles.empty}>No items or targets to match.</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className={styles.wrapper}>
+      <p className={styles.instruction}>
+        Drag each item from the left and drop it on the correct match on the right.
+      </p>
+
+      <DndContext
+        sensors={sensors}
+        collisionDetection={closestCenter}
+        onDragEnd={handleDragEnd}
+      >
+        <div className={styles.columns}>
+          <div className={styles.column}>
+            <h3 className={styles.columnTitle}>Items</h3>
+            <ul className={styles.list} role="list">
+              {unmatchedItems.map((item) => (
+                <DraggableItem
+                  key={item.id}
+                  item={item}
+                  disabled={hasCompleted}
+                />
+              ))}
+            </ul>
+          </div>
+
+          <div className={styles.column}>
+            <h3 className={styles.columnTitle}>Matches</h3>
+            <ul className={styles.list} role="list">
+              {shuffledTargets.map((target) => (
+                <DroppableTarget
+                  key={target.id}
+                  target={target}
+                  matchedItem={matchedTargetIds.has(target.id) ? itemsByMatchId.get(target.id) ?? null : null}
+                  disabled={hasCompleted}
+                />
+              ))}
+            </ul>
+          </div>
+        </div>
+      </DndContext>
+    </div>
+  );
+};
+
+export default MatchingActivity;

package/MatchingActivity/style.module.css

@@ -0,0 +1,195 @@
+/* ---- Wrapper ---- */
+.wrapper {
+  --match-accent: #2563eb;
+  --match-accent-hover: #1d4ed8;
+  --match-bg: #f8fafc;
+  --match-border: #e2e8f0;
+  --match-text: #1e293b;
+  --match-muted: #64748b;
+  --match-success: #16a34a;
+  --match-success-bg: #dcfce7;
+  --match-over: #93c5fd;
+  --match-over-bg: #eff6ff;
+  --match-radius: 12px;
+  --match-shadow: 0 4px 20px rgba(0, 0, 0, 0.08);
+  font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;
+  color: var(--match-text);
+  max-width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+}
+
+/* ---- Instruction ---- */
+.instruction {
+  margin: 0;
+  font-size: 0.9375rem;
+  color: var(--match-muted);
+  line-height: 1.5;
+}
+
+/* ---- Two columns ---- */
+.columns {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1.5rem;
+  align-items: start;
+}
+
+@media (max-width: 640px) {
+  .columns {
+    grid-template-columns: 1fr;
+  }
+}
+
+.column {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  padding: 1.25rem;
+  background: var(--match-bg);
+  border: 2px solid var(--match-border);
+  border-radius: var(--match-radius);
+  min-height: 200px;
+  transition: border-color 0.25s ease, box-shadow 0.25s ease;
+}
+
+.columnTitle {
+  margin: 0;
+  font-size: 0.875rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--match-muted);
+}
+
+/* ---- Lists ---- */
+.list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+/* ---- Draggable items (left column) ---- */
+.item {
+  display: flex;
+  align-items: center;
+  padding: 1rem 1.25rem;
+  background: #fff;
+  border: 2px solid var(--match-border);
+  border-radius: var(--match-radius);
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05);
+  cursor: grab;
+  transition:
+    transform 0.25s ease,
+    border-color 0.25s ease,
+    background-color 0.25s ease,
+    box-shadow 0.25s ease;
+  touch-action: none;
+}
+
+.item:hover {
+  border-color: var(--match-accent);
+  box-shadow: 0 2px 8px rgba(37, 99, 235, 0.12);
+}
+
+.item:active {
+  cursor: grabbing;
+}
+
+.itemDragging {
+  opacity: 0.95;
+  transform: scale(1.02);
+  box-shadow: var(--match-shadow);
+  border-color: var(--match-accent);
+  z-index: 10;
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+
+.itemDisabled {
+  cursor: default;
+  opacity: 0.7;
+}
+
+.itemContent {
+  font-size: 1rem;
+  font-weight: 500;
+  line-height: 1.4;
+  flex: 1;
+}
+
+/* ---- Droppable targets (right column) ---- */
+.target {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+  padding: 1rem 1.25rem;
+  background: #fff;
+  border: 2px dashed var(--match-border);
+  border-radius: var(--match-radius);
+  min-height: 3.5rem;
+  transition:
+    border-color 0.25s ease,
+    background-color 0.25s ease,
+    transform 0.25s ease,
+    box-shadow 0.25s ease;
+}
+
+.targetOver {
+  border-style: solid;
+  border-color: var(--match-accent);
+  background: var(--match-over-bg);
+  transform: scale(1.01);
+  box-shadow: 0 2px 12px rgba(37, 99, 235, 0.15);
+}
+
+.targetMatched {
+  border-style: solid;
+  border-color: var(--match-success);
+  background: var(--match-success-bg);
+  animation: matchSuccess 0.4s ease-out forwards;
+}
+
+@keyframes matchSuccess {
+  from {
+    transform: scale(1.02);
+    box-shadow: 0 0 0 0 rgba(22, 163, 74, 0.4);
+  }
+  to {
+    transform: scale(1);
+    box-shadow: 0 2px 8px rgba(22, 163, 74, 0.2);
+  }
+}
+
+.targetContent {
+  font-size: 0.875rem;
+  font-weight: 600;
+  color: var(--match-muted);
+  line-height: 1.3;
+}
+
+.targetPlaceholder {
+  font-size: 0.8125rem;
+  color: var(--match-border);
+  font-style: italic;
+}
+
+.matchedContent {
+  font-size: 1rem;
+  font-weight: 500;
+  color: var(--match-success);
+  line-height: 1.4;
+  transition: opacity 0.3s ease;
+}
+
+/* ---- Empty state ---- */
+.empty {
+  margin: 0;
+  padding: 2rem;
+  text-align: center;
+  color: var(--match-muted);
+  font-size: 1rem;
+}

package/README.md

@@ -8,6 +8,18 @@ A collection of reusable React components for e-learning applications.
 
 A fully-featured flashcard component with 3D flip animations. See `FlashcardDeck/README.md` for detailed documentation.
 
+### InteractiveTimeline
+
+A horizontal, draggable timeline that displays a series of events with clickable markers and prev/next navigation. See `InteractiveTimeline/README.md` for detailed documentation.
+
+### SortingActivity
+
+A drag-and-drop sorting activity component where users reorder items into the correct sequence. Uses @dnd-kit/sortable and pure CSS animations. See `SortingActivity/README.md` for detailed documentation.
+
+### MatchingActivity
+
+A drag-and-drop matching activity where users match items from one column to the correct targets in another. Uses @dnd-kit/core and pure CSS animations. See `MatchingActivity/README.md` for detailed documentation.
+
 ## Getting Started
 
 ### Installation
@@ -38,6 +50,18 @@ elearning-components/
 │   ├── FlashcardDeck.css   # Styles
 │   ├── index.js            # Export
 │   └── README.md           # Documentation
+├── InteractiveTimeline/    # InteractiveTimeline component
+│   ├── index.tsx           # Component and exports
+│   ├── style.module.css    # CSS Modules styles
+│   └── README.md           # Documentation
+├── SortingActivity/        # SortingActivity component
+│   ├── index.tsx           # Component and exports
+│   ├── style.module.css    # CSS Modules styles
+│   └── README.md           # Documentation
+├── MatchingActivity/       # MatchingActivity 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/SortingActivity/README.md

@@ -0,0 +1,96 @@
+# SortingActivity
+
+A React component for e-learning that lets users drag and drop items to arrange them in the correct order. Built with **@dnd-kit/sortable** for reordering and **pure CSS** for transitions and transforms.
+
+## File structure
+
+```
+SortingActivity/
+├── index.tsx         # Component, types, and exports
+├── style.module.css  # CSS Modules styles
+└── README.md         # This file
+```
+
+## Props
+
+### `SortingActivityProps`
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `items` | `SortableItem[]` | Yes | List of items to sort. Each item has an `id` and `content`. |
+| `correctOrder` | `string[]` | Yes | Array of item IDs in the correct sequence (in order). |
+| `onComplete` | `(result: { isCorrect: boolean }) => void` | Yes | Callback invoked when "Check Answer" is clicked. Receives whether the user's order matches `correctOrder`. |
+
+### `SortableItem`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique identifier for the item (used for ordering and feedback). |
+| `content` | `string` | Text displayed on the item. |
+
+## Functionality
+
+- **Random initial order**: Items are shuffled when the component mounts.
+- **Drag and drop**: Users can reorder items using mouse or touch; reordering uses @dnd-kit/sortable.
+- **Check Answer**: Compares the current order to `correctOrder` and shows visual feedback:
+  - Correct: all items highlighted green; success message shown.
+  - Incorrect: each item marked correct (green) or incorrect (red); error message shown.
+- **Reset**: Restores the list to its initial shuffled order and clears feedback.
+- **onComplete**: Called when "Check Answer" is clicked with `{ isCorrect: boolean }`.
+
+## Styling and animations
+
+- **CSS Modules**: All styles live in `style.module.css`; class names are scoped.
+- **Transitions**: Hover and drag states use CSS transitions (transform, border-color, background, box-shadow).
+- **Feedback animation**: Correct/incorrect feedback uses a short scale + fade-in animation.
+- **Message animation**: Feedback message uses a slide-in animation.
+
+## Usage example
+
+```tsx
+import React from 'react';
+import SortingActivity, {
+  type SortableItem,
+  type SortingActivityProps,
+} from './SortingActivity';
+
+const items: SortableItem[] = [
+  { id: '1', content: 'First step: Gather materials' },
+  { id: '2', content: 'Second step: Prepare the workspace' },
+  { id: '3', content: 'Third step: Assemble the parts' },
+  { id: '4', content: 'Fourth step: Test and verify' },
+];
+
+const correctOrder = ['1', '2', '3', '4'];
+
+function App() {
+  const handleComplete: SortingActivityProps['onComplete'] = (result) => {
+    console.log('Answer correct:', result.isCorrect);
+  };
+
+  return (
+    <div style={{ padding: '2rem', maxWidth: 500 }}>
+      <SortingActivity
+        items={items}
+        correctOrder={correctOrder}
+        onComplete={handleComplete}
+      />
+    </div>
+  );
+}
+```
+
+In this example, the component shows four steps in a random order. Users drag items to arrange them, click "Check Answer" to see feedback, and "Reset" to restore the initial order.
+
+## Dependencies
+
+- **React** 18.x
+- **@dnd-kit/core**
+- **@dnd-kit/sortable**
+- **@dnd-kit/utilities**
+
+## Accessibility
+
+- List has `role="list"`.
+- Buttons use `aria-label` where appropriate.
+- Feedback message has `role="status"` and `aria-live="polite"` for screen readers.