@zomako/elearning-components 2.0.3 → 2.0.4

package/InteractiveTimeline/README.md

@@ -0,0 +1,117 @@
+# InteractiveTimeline
+
+A horizontal, draggable timeline component for React that displays a series of events. Users can scroll by dragging the track, click event markers to view details, or use previous/next buttons. Built with **pure CSS** for animations and **native browser events** for drag-to-scroll (no gesture library).
+
+## File structure
+
+```
+InteractiveTimeline/
+├── index.tsx         # Component and types
+├── style.module.css  # CSS Modules styles
+└── README.md         # This file
+```
+
+## Props
+
+### `InteractiveTimelineProps`
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `events` | `TimelineEvent[]` | Yes | List of timeline events to display. |
+| `defaultActiveId` | `string` | No | ID of the event to show as active on first render. If omitted or invalid, the first event is active. |
+
+### `TimelineEvent`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique identifier for the event (used for active state and `defaultActiveId`). |
+| `year` | `string` | Year or date label shown on the marker and in the content panel (e.g. `"2020"`, `"Q1 2023"`). |
+| `title` | `string` | Short title for the event (shown on the marker and as the content heading). |
+| `content` | `React.ReactNode` | Detailed content (JSX, text, etc.) shown in the panel when the event is active. |
+
+## Functionality
+
+- **Horizontal layout**: Events are laid out in a single horizontal row.
+- **Drag-to-scroll**: The timeline track is draggable with mouse or touch; dragging moves the timeline horizontally. Implemented with native `mousedown` / `mousemove` / `mouseup` and `touchstart` / `touchmove` / `touchend`.
+- **Click to select**: Clicking an event marker sets that event as active and shows its content in the panel above.
+- **Active state**: The active event marker is visually distinct (e.g. larger scale, accent color, filled background).
+- **Previous / Next**: Buttons move to the previous or next event and update the active event and content.
+- **Smooth scrolling**: When the active event changes, the track scrolls so the active marker is brought into view using smooth scrolling (CSS + `scrollTo({ behavior: 'smooth' })` where applicable).
+
+## Animations and styling
+
+- **CSS transitions** are used for:
+  - Scroll behavior on the track.
+  - Marker hover and active state (scale, color, border).
+  - Nav button hover and disabled state.
+- **Content panel**: When the active event changes, the new content uses a short **fade + slide-up** animation (keyframes in the CSS module).
+- **Styling**: All styles are in `style.module.css` (CSS Modules). The design uses a clear typographic hierarchy (year → title → body), accent color for the active event and interactive states, and a simple card-style content panel.
+
+## Usage example
+
+```tsx
+import React from 'react';
+import InteractiveTimeline, {
+  type TimelineEvent,
+} from './InteractiveTimeline';
+
+const events: TimelineEvent[] = [
+  {
+    id: '1',
+    year: '2020',
+    title: 'Project kickoff',
+    content: (
+      <p>
+        The project started with a small team and a clear roadmap
+        for the first year.
+      </p>
+    ),
+  },
+  {
+    id: '2',
+    year: '2021',
+    title: 'First release',
+    content: (
+      <p>
+        We shipped the first public version and gathered feedback
+        from early adopters.
+      </p>
+    ),
+  },
+  {
+    id: '3',
+    year: '2022',
+    title: 'Scale and grow',
+    content: (
+      <p>
+        Focus shifted to performance and scaling the platform
+        for enterprise customers.
+      </p>
+    ),
+  },
+];
+
+function App() {
+  return (
+    <div style={{ padding: '2rem', maxWidth: 800 }}>
+      <InteractiveTimeline
+        events={events}
+        defaultActiveId="2"
+      />
+    </div>
+  );
+}
+```
+
+In this example, the timeline shows three events, with the second one (`"2"`) active on initial render. Users can drag the track to scroll, click any marker to view its content, or use the ‹ › buttons to move between events.
+
+## Dependencies
+
+- **React** (e.g. 18.x).
+- No extra libraries: animations are pure CSS, and drag-to-scroll uses only native DOM events.
+
+## Accessibility
+
+- Event markers are focusable buttons with `aria-pressed` reflecting the active state.
+- Nav buttons use `aria-label` (e.g. "Previous event", "Next event").
+- The track has `role="list"` and `aria-label="Timeline events"` for the list of events.

package/InteractiveTimeline/index.tsx

@@ -0,0 +1,191 @@
+import React, { useRef, useState, useCallback, useEffect } from 'react';
+import styles from './style.module.css';
+
+export interface TimelineEvent {
+  id: string;
+  year: string;
+  title: string;
+  content: React.ReactNode;
+}
+
+export interface InteractiveTimelineProps {
+  events: TimelineEvent[];
+  defaultActiveId?: string;
+}
+
+const InteractiveTimeline: React.FC<InteractiveTimelineProps> = ({
+  events,
+  defaultActiveId,
+}) => {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const [activeId, setActiveId] = useState<string | null>(() => {
+    if (defaultActiveId && events.some((e) => e.id === defaultActiveId)) {
+      return defaultActiveId;
+    }
+    return events.length > 0 ? events[0].id : null;
+  });
+  const [isDragging, setIsDragging] = useState(false);
+  const dragState = useRef({ startX: 0, scrollLeft: 0 });
+
+  const activeEvent = events.find((e) => e.id === activeId) ?? events[0];
+  const activeIndex = events.findIndex((e) => e.id === activeId);
+
+  const handleMarkerClick = useCallback(
+    (id: string) => {
+      setActiveId(id);
+    },
+    []
+  );
+
+  const goPrevious = useCallback(() => {
+    if (activeIndex > 0) {
+      setActiveId(events[activeIndex - 1].id);
+    }
+  }, [activeIndex, events]);
+
+  const goNext = useCallback(() => {
+    if (activeIndex < events.length - 1 && activeIndex >= 0) {
+      setActiveId(events[activeIndex + 1].id);
+    }
+  }, [activeIndex, events]);
+
+  const handlePointerDown = useCallback(
+    (e: React.MouseEvent | React.TouchEvent) => {
+      if (!scrollRef.current) return;
+      const target = e.target as HTMLElement;
+      if (target.closest(`.${styles.marker}`)) return;
+      const clientX = 'touches' in e ? e.touches[0].clientX : e.clientX;
+      setIsDragging(true);
+      dragState.current = {
+        startX: clientX,
+        scrollLeft: scrollRef.current.scrollLeft,
+      };
+    },
+    []
+  );
+
+  const handlePointerMove = useCallback(
+    (e: MouseEvent | TouchEvent) => {
+      if (!isDragging || !scrollRef.current) return;
+      e.preventDefault();
+      const clientX = 'touches' in e ? e.touches[0].clientX : e.clientX;
+      const dx = dragState.current.startX - clientX;
+      scrollRef.current.scrollLeft = dragState.current.scrollLeft + dx;
+    },
+    [isDragging]
+  );
+
+  const handlePointerUp = useCallback(() => {
+    setIsDragging(false);
+  }, []);
+
+  useEffect(() => {
+    if (!isDragging) return;
+    window.addEventListener('mousemove', handlePointerMove, { passive: false });
+    window.addEventListener('mouseup', handlePointerUp);
+    window.addEventListener('touchmove', handlePointerMove, { passive: false });
+    window.addEventListener('touchend', handlePointerUp);
+    return () => {
+      window.removeEventListener('mousemove', handlePointerMove);
+      window.removeEventListener('mouseup', handlePointerUp);
+      window.removeEventListener('touchmove', handlePointerMove);
+      window.removeEventListener('touchend', handlePointerUp);
+    };
+  }, [isDragging, handlePointerMove, handlePointerUp]);
+
+  useEffect(() => {
+    if (!scrollRef.current || !activeId) return;
+    const marker = scrollRef.current.querySelector(
+      `[data-event-id="${activeId}"]`
+    ) as HTMLElement | null;
+    if (marker) {
+      const container = scrollRef.current;
+      const half = container.clientWidth / 2;
+      const target =
+        marker.offsetLeft - half + marker.offsetWidth / 2;
+      container.scrollTo({
+        left: Math.max(0, target),
+        behavior: 'smooth',
+      });
+    }
+  }, [activeId]);
+
+  if (!events || events.length === 0) {
+    return (
+      <div className={styles.wrapper}>
+        <p className={styles.empty}>No events to display.</p>
+      </div>
+    );
+  }
+
+  const canGoPrevious = activeIndex > 0;
+  const canGoNext = activeIndex >= 0 && activeIndex < events.length - 1;
+
+  return (
+    <div className={styles.wrapper}>
+      <div className={styles.contentPanel}>
+        <div key={activeId} className={styles.contentSlide}>
+          {activeEvent && (
+            <>
+              <span className={styles.contentYear}>{activeEvent.year}</span>
+              <h2 className={styles.contentTitle}>{activeEvent.title}</h2>
+              <div className={styles.contentBody}>{activeEvent.content}</div>
+            </>
+          )}
+        </div>
+      </div>
+
+      <div className={styles.timelineSection}>
+        <button
+          type="button"
+          className={styles.navButton}
+          onClick={goPrevious}
+          disabled={!canGoPrevious}
+          aria-label="Previous event"
+        >
+          ‹
+        </button>
+
+        <div
+          ref={scrollRef}
+          className={`${styles.track} ${isDragging ? styles.dragging : ''}`}
+          onMouseDown={handlePointerDown}
+          onTouchStart={handlePointerDown}
+          role="list"
+          aria-label="Timeline events"
+        >
+          <div className={styles.trackInner}>
+            {events.map((event) => (
+              <button
+                type="button"
+                key={event.id}
+                data-event-id={event.id}
+                className={`${styles.marker} ${
+                  event.id === activeId ? styles.markerActive : ''
+                }`}
+                onClick={() => handleMarkerClick(event.id)}
+                aria-pressed={event.id === activeId}
+                aria-label={`${event.year}: ${event.title}`}
+              >
+                <span className={styles.markerYear}>{event.year}</span>
+                <span className={styles.markerTitle}>{event.title}</span>
+              </button>
+            ))}
+          </div>
+        </div>
+
+        <button
+          type="button"
+          className={styles.navButton}
+          onClick={goNext}
+          disabled={!canGoNext}
+          aria-label="Next event"
+        >
+          ›
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default InteractiveTimeline;

package/InteractiveTimeline/style.module.css

@@ -0,0 +1,211 @@
+/* ---- Wrapper ---- */
+.wrapper {
+  --timeline-accent: #2563eb;
+  --timeline-accent-hover: #1d4ed8;
+  --timeline-bg: #f8fafc;
+  --timeline-line: #e2e8f0;
+  --timeline-text: #1e293b;
+  --timeline-muted: #64748b;
+  --timeline-radius: 12px;
+  --timeline-shadow: 0 4px 20px rgba(0, 0, 0, 0.08);
+  font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;
+  color: var(--timeline-text);
+  max-width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+}
+
+/* ---- Content panel ---- */
+.contentPanel {
+  background: var(--timeline-bg);
+  border-radius: var(--timeline-radius);
+  padding: 1.75rem 2rem;
+  box-shadow: var(--timeline-shadow);
+  min-height: 140px;
+  overflow: hidden;
+}
+
+.contentSlide {
+  animation: contentIn 0.35s ease-out forwards;
+}
+
+@keyframes contentIn {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.contentYear {
+  display: inline-block;
+  font-size: 0.8125rem;
+  font-weight: 600;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  color: var(--timeline-accent);
+  margin-bottom: 0.35rem;
+}
+
+.contentTitle {
+  font-size: 1.375rem;
+  font-weight: 700;
+  line-height: 1.3;
+  margin: 0 0 0.75rem 0;
+  color: var(--timeline-text);
+}
+
+.contentBody {
+  font-size: 1rem;
+  line-height: 1.6;
+  color: var(--timeline-muted);
+}
+
+.contentBody p {
+  margin: 0 0 0.5rem 0;
+}
+
+.contentBody p:last-child {
+  margin-bottom: 0;
+}
+
+/* ---- Timeline section ---- */
+.timelineSection {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.navButton {
+  flex-shrink: 0;
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: 50%;
+  border: 2px solid var(--timeline-line);
+  background: #fff;
+  color: var(--timeline-text);
+  font-size: 1.5rem;
+  line-height: 1;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: border-color 0.2s ease, background 0.2s ease, color 0.2s ease;
+}
+
+.navButton:hover:not(:disabled) {
+  border-color: var(--timeline-accent);
+  background: var(--timeline-accent);
+  color: #fff;
+}
+
+.navButton:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+/* ---- Track (draggable scroll area) ---- */
+.track {
+  flex: 1;
+  overflow-x: auto;
+  overflow-y: hidden;
+  scroll-behavior: smooth;
+  scrollbar-width: thin;
+  scrollbar-color: var(--timeline-line) transparent;
+  cursor: grab;
+  padding: 0.5rem 0;
+  margin: 0 -0.5rem;
+}
+
+.track.dragging {
+  cursor: grabbing;
+  scroll-behavior: auto;
+}
+
+.track::-webkit-scrollbar {
+  height: 6px;
+}
+
+.track::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.track::-webkit-scrollbar-thumb {
+  background: var(--timeline-line);
+  border-radius: 3px;
+}
+
+.trackInner {
+  display: flex;
+  gap: 0.75rem;
+  padding: 0 0.25rem;
+  min-width: min-content;
+}
+
+/* ---- Event markers ---- */
+.marker {
+  flex-shrink: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.75rem 1rem;
+  min-width: 100px;
+  border: 2px solid var(--timeline-line);
+  border-radius: var(--timeline-radius);
+  background: #fff;
+  color: var(--timeline-muted);
+  font: inherit;
+  cursor: pointer;
+  text-align: center;
+  transition: transform 0.25s ease, border-color 0.25s ease, background 0.25s ease,
+    color 0.25s ease, box-shadow 0.25s ease;
+}
+
+.marker:hover {
+  border-color: var(--timeline-accent);
+  color: var(--timeline-accent);
+}
+
+.markerActive {
+  border-color: var(--timeline-accent);
+  background: var(--timeline-accent);
+  color: #fff;
+  transform: scale(1.08);
+  box-shadow: var(--timeline-shadow);
+}
+
+.markerActive:hover {
+  background: var(--timeline-accent-hover);
+  border-color: var(--timeline-accent-hover);
+  color: #fff;
+}
+
+.markerYear {
+  font-size: 0.8125rem;
+  font-weight: 700;
+  letter-spacing: 0.02em;
+}
+
+.markerTitle {
+  font-size: 0.8125rem;
+  font-weight: 500;
+  line-height: 1.25;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+/* ---- Empty state ---- */
+.empty {
+  margin: 0;
+  padding: 2rem;
+  text-align: center;
+  color: var(--timeline-muted);
+  font-size: 1rem;
+}

package/MatchingActivity/README.md

@@ -0,0 +1,104 @@
+# MatchingActivity
+
+A React component for e-learning that lets users drag items from one column and drop them on the correct matching target in another column. Built with **@dnd-kit/core** for drag-and-drop and **pure CSS** for transitions and transforms.
+
+## File structure
+
+```
+MatchingActivity/
+├── index.tsx         # Component, types, and exports
+├── style.module.css   # CSS Modules styles
+└── README.md         # This file
+```
+
+## Props
+
+### `MatchingActivityProps`
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `items` | `MatchItem[]` | Yes | Draggable items. Each has an `id`, `content`, and `matchId` pointing to the target it should match. |
+| `targets` | `MatchTarget[]` | Yes | Drop targets. Each has an `id` and `content`. A correct match is when `item.matchId === target.id`. |
+| `onComplete` | `(result: { score: number; correct: number; total: number }) => void` | Yes | Callback invoked when all pairs are correctly matched. Receives `score` (0–100), `correct` count, and `total` count. |
+
+### `MatchItem`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique identifier for the draggable item. |
+| `content` | `string` | Text displayed on the item. |
+| `matchId` | `string` | The `id` of the target this item should match with. |
+
+### `MatchTarget`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique identifier for the target (must match `MatchItem.matchId` for the correct pair). |
+| `content` | `string` | Text displayed for the target (e.g. the label or definition to match). |
+
+## Functionality
+
+- **Two columns**: Left column shows draggable items, right column shows targets. Both are shuffled on initial render.
+- **Drag and drop**: Users drag an item and drop it on a target. Only the pointer is used for drag (no keyboard sortable).
+- **Correct match**: When `item.matchId === target.id`, the pair locks: the item is removed from the left column and shown next to the target on the right. Both become non-interactive.
+- **Visual feedback**: Droppable targets highlight when a draggable is over them. Correctly matched pairs get a success style and a short CSS animation.
+- **Completion**: When every target has a correct match, `onComplete` is called once with `{ score, correct, total }` (e.g. `score` as a percentage 0–100).
+
+## 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.
+- **Drag state**: Dragging item uses a slight scale and shadow (transform/box-shadow).
+- **Match success**: Correct pairs use a short scale + box-shadow keyframe animation for instant visual feedback.
+
+## Usage example
+
+```tsx
+import React from 'react';
+import MatchingActivity, {
+  type MatchItem,
+  type MatchTarget,
+  type MatchingActivityProps,
+} from './MatchingActivity';
+
+const items: MatchItem[] = [
+  { id: 'item-1', content: 'Paris', matchId: 'target-capital-fr' },
+  { id: 'item-2', content: 'Berlin', matchId: 'target-capital-de' },
+  { id: 'item-3', content: 'Madrid', matchId: 'target-capital-es' },
+];
+
+const targets: MatchTarget[] = [
+  { id: 'target-capital-fr', content: 'Capital of France' },
+  { id: 'target-capital-de', content: 'Capital of Germany' },
+  { id: 'target-capital-es', content: 'Capital of Spain' },
+];
+
+function App() {
+  const handleComplete: MatchingActivityProps['onComplete'] = (result) => {
+    console.log('Score:', result.score, 'Correct:', result.correct, 'Total:', result.total);
+  };
+
+  return (
+    <div style={{ padding: '2rem', maxWidth: 700 }}>
+      <MatchingActivity
+        items={items}
+        targets={targets}
+        onComplete={handleComplete}
+      />
+    </div>
+  );
+}
+```
+
+In this example, the left column shows the three cities in random order and the right column shows the three “Capital of …” labels in random order. Users drag each city onto the correct description; when all three are matched, `onComplete` is called with the final score.
+
+## Dependencies
+
+- **React** 18.x
+- **@dnd-kit/core**
+
+## Accessibility
+
+- Lists use `role="list"`.
+- Targets show a “Drop here” placeholder when empty; matched pairs show the matched content.
+- Draggable items are keyboard-focusable via the pointer sensor; consider adding keyboard instructions in your app if needed.