coursecode 0.1.0

package/framework/js/components/ui-components/interactive-image.js

@@ -0,0 +1,235 @@
+/**
+ * @file interactive-image.js
+ * @description Interactive image component with hotspots that open modals and track engagement.
+ * Supports integration with Accordion for side-by-side interaction.
+ */
+
+export const schema = {
+    type: 'interactive-image',
+    description: 'Image with clickable hotspots for modals or accordion integration',
+    example: `<div data-component="interactive-image" class="interactive-image" style="position: relative; display: inline-block;">
+  <img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='250' fill='%23f1f5f9'%3E%3Crect width='400' height='250' rx='8'/%3E%3Ctext x='50%25' y='50%25' dominant-baseline='middle' text-anchor='middle' fill='%2394a3b8' font-family='system-ui' font-size='14'%3EInteractive Diagram%3C/text%3E%3C/svg%3E" alt="Interactive diagram">
+  <button data-hotspot-id="feature-a" data-title="Feature A" data-body="Details about Feature A" class="hotspot" style="position: absolute; top: 30%; left: 25%; width: 24px; height: 24px; border-radius: 50%; background: #3b82f6; border: 2px solid white; cursor: pointer;" aria-label="Feature A"></button>
+  <button data-hotspot-id="feature-b" data-title="Feature B" data-body="Details about Feature B" class="hotspot" style="position: absolute; top: 60%; left: 65%; width: 24px; height: 24px; border-radius: 50%; background: #f59e0b; border: 2px solid white; cursor: pointer;" aria-label="Feature B"></button>
+</div>`,
+    properties: {
+        accordionId: { type: 'string', dataAttribute: 'data-accordion-id' }
+    },
+    structure: {
+        container: '[data-component="interactive-image"]',
+        children: {
+            hotspot: { selector: '[data-hotspot-id]', required: true, minItems: 1 }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: 'interactions/interactive-image.css',
+    engagementTracking: 'viewAllHotspots',
+    emitsEvents: []
+};
+
+import * as Modal from './modal.js';
+import engagementManager from '../../engagement/engagement-manager.js';
+import * as NavigationState from '../../navigation/NavigationState.js';
+import { logger } from '../../utilities/logger.js';
+import { eventBus } from '../../core/event-bus.js';
+
+/**
+ * Initializes interactive image components.
+ * @param {HTMLElement} root - The container element (or selector).
+ * @param {object} options - Configuration options.
+ */
+export function init(root, _options = {}) {
+    const container = typeof root === 'string' ? document.querySelector(root) : root;
+    if (!container) return;
+
+    const hotspots = Array.from(container.querySelectorAll('[data-hotspot-id]'));
+    if (!hotspots.length) return;
+
+    const currentSlideId = NavigationState.getCurrentSlideId();
+    const imageId = container.id || `interactive-image-${Math.random().toString(36).substr(2, 9)}`;
+    const accordionId = container.dataset.accordionId;
+
+    // Register with EngagementManager if on a slide
+    if (currentSlideId) {
+        const hotspotIds = hotspots.map(h => h.dataset.hotspotId);
+        if (typeof engagementManager.registerInteractiveImage === 'function') {
+            engagementManager.registerInteractiveImage(currentSlideId, hotspotIds);
+        }
+    }
+
+    // Setup Accordion Integration if ID is provided
+    let accordionElement = null;
+    if (accordionId) {
+        accordionElement = document.getElementById(accordionId);
+        if (accordionElement) {
+            setupAccordionIntegration(container, hotspots, accordionElement, accordionId);
+        } else {
+            logger.warn(`[InteractiveImage] Accordion #${accordionId} not found for image ${imageId}`);
+        }
+    }
+
+    hotspots.forEach(hotspot => {
+        // Add accessibility attributes
+        hotspot.setAttribute('role', 'button');
+        hotspot.setAttribute('tabindex', '0');
+        if (!hotspot.getAttribute('aria-label')) {
+            hotspot.setAttribute('aria-label', hotspot.dataset.title || 'View details');
+        }
+
+        const handleClick = (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+
+            const id = hotspot.dataset.hotspotId;
+
+            // If accordion is linked, toggle it instead of modal
+            if (accordionElement) {
+                const button = accordionElement.querySelector(`[data-panel="${id}"]`);
+                if (button) {
+                    button.click(); // Simulate click to toggle
+                }
+            } else {
+                // Default Modal Behavior
+                const title = hotspot.dataset.title || 'Details';
+                const body = hotspot.dataset.body || hotspot.innerHTML;
+
+                Modal.show({
+                    title: title,
+                    body: body,
+                    footer: '<button class="btn btn-primary" data-action="close-modal">Close</button>',
+                    config: { closeOnBackdrop: true, closeOnEscape: true }
+                });
+            }
+
+            // Mark as viewed visually
+            hotspot.classList.add('viewed');
+
+            // Track engagement
+            if (currentSlideId && typeof engagementManager.trackInteractiveImageView === 'function') {
+                engagementManager.trackInteractiveImageView(currentSlideId, id);
+            }
+        };
+
+        hotspot.addEventListener('click', handleClick);
+        hotspot.addEventListener('keydown', (e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+                handleClick(e);
+            }
+        });
+    });
+
+    logger.debug(`[InteractiveImage] Initialized ${hotspots.length} hotspots for ${imageId}`);
+}
+
+/**
+ * Sets up bi-directional sync between image hotspots and accordion panels.
+ */
+function setupAccordionIntegration(imageContainer, hotspots, accordionElement, accordionId) {
+    // Map hotspots by ID for quick access
+    const hotspotMap = new Map(hotspots.map(h => [h.dataset.hotspotId, h]));
+
+    // 1. Listen for Accordion Toggles (via EventBus)
+    const handleAccordionToggle = (data) => {
+        if (data.accordionId !== accordionId) return;
+
+        const hotspot = hotspotMap.get(data.panelId);
+        if (hotspot) {
+            if (data.isOpen) {
+                hotspot.classList.add('active');
+                hotspot.classList.add('viewed'); // Opening accordion counts as viewing
+
+                // Also track engagement if opened via accordion
+                const currentSlideId = NavigationState.getCurrentSlideId();
+                if (currentSlideId && typeof engagementManager.trackInteractiveImageView === 'function') {
+                    engagementManager.trackInteractiveImageView(currentSlideId, data.panelId);
+                }
+            } else {
+                hotspot.classList.remove('active');
+            }
+        }
+    };
+
+    eventBus.on('accordion:toggled', handleAccordionToggle);
+
+    // 2. Hover Effects (Accordion Button -> Image Hotspot)
+    const buttons = accordionElement.querySelectorAll('[data-panel]');
+    buttons.forEach(btn => {
+        const panelId = btn.dataset.panel;
+        const hotspot = hotspotMap.get(panelId);
+
+        if (hotspot) {
+            btn.addEventListener('mouseenter', () => {
+                hotspot.classList.add('highlighted');
+            });
+
+            btn.addEventListener('mouseleave', () => {
+                hotspot.classList.remove('highlighted');
+            });
+
+            btn.addEventListener('focus', () => {
+                hotspot.classList.add('highlighted');
+            });
+
+            btn.addEventListener('blur', () => {
+                hotspot.classList.remove('highlighted');
+            });
+        }
+    });
+
+    // 3. Click Outside to Deselect
+    // Closes any open accordion panel if clicking outside the accordion.
+    // Note: Hotspots stop propagation, so clicking a hotspot won't trigger this.
+    // Clicking the image background (which bubbles) WILL trigger this, effectively deselecting.
+    const handleOutsideClick = (e) => {
+        // Check if click is inside accordion
+        const isInsideAccordion = accordionElement.contains(e.target);
+
+        if (!isInsideAccordion) {
+            // Find currently open panel button
+            const openButton = accordionElement.querySelector('.accordion-button[aria-expanded="true"]');
+            if (openButton) {
+                openButton.click(); // Simulate click to close
+            }
+        }
+    };
+
+    // Component lifecycle cleanup using MutationObserver
+    // When the container is removed from DOM, we automatically clean up all listeners
+    const cleanupListeners = () => {
+        document.removeEventListener('click', safeHandleOutsideClick);
+        eventBus.off('accordion:toggled', handleAccordionToggle);
+        if (observer) {
+            observer.disconnect();
+        }
+    };
+
+    const safeHandleOutsideClick = (e) => {
+        if (!document.body.contains(imageContainer)) {
+            cleanupListeners();
+            return;
+        }
+        handleOutsideClick(e);
+    };
+
+    // Use MutationObserver to detect when container is removed from DOM
+    const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+            for (const node of mutation.removedNodes) {
+                if (node === imageContainer || node.contains?.(imageContainer)) {
+                    cleanupListeners();
+                    return;
+                }
+            }
+        }
+    });
+
+    // Observe parent for child removals (handles SPA navigation cleanup)
+    if (imageContainer.parentNode) {
+        observer.observe(imageContainer.parentNode, { childList: true });
+    }
+
+    document.addEventListener('click', safeHandleOutsideClick);
+}

package/framework/js/components/ui-components/interactive-timeline.js

@@ -0,0 +1,285 @@
+/**
+ * @file interactive-timeline.js
+ * @description Interactive timeline component with expandable events and engagement tracking.
+ * 
+ * Usage example:
+ *   <div class="interactive-timeline" data-component="interactive-timeline">
+ *     <div class="timeline-event" data-event-id="event1">
+ *       <div class="timeline-marker"></div>
+ *       <div class="timeline-date">2020</div>
+ *       <div class="timeline-summary">
+ *         <h4>Event Title</h4>
+ *         <p>Brief description...</p>
+ *       </div>
+ *       <div class="timeline-details">
+ *         <p>Expanded content revealed on click...</p>
+ *       </div>
+ *     </div>
+ *   </div>
+ */
+
+export const schema = {
+    type: 'interactive-timeline',
+    description: 'Timeline with expandable events and engagement tracking',
+    example: `<div data-component="interactive-timeline" class="interactive-timeline">
+  <div class="timeline-event active" data-event-id="event-1"><div class="timeline-event-marker"></div><div class="timeline-event-label">Phase 1</div><div class="timeline-event-content"><h3>Discovery</h3><p>Research and planning phase.</p></div></div>
+  <div class="timeline-event" data-event-id="event-2"><div class="timeline-event-marker"></div><div class="timeline-event-label">Phase 2</div><div class="timeline-event-content"><h3>Development</h3><p>Building core functionality.</p></div></div>
+  <div class="timeline-event" data-event-id="event-3"><div class="timeline-event-marker"></div><div class="timeline-event-label">Phase 3</div><div class="timeline-event-content"><h3>Launch</h3><p>Deployment and go-live.</p></div></div>
+</div>`,
+    properties: {
+        mode: { type: 'string', enum: ['free', 'sequential'], default: 'free', dataAttribute: 'data-timeline-mode' }
+    },
+    structure: {
+        container: '[data-component="interactive-timeline"]',
+        children: {
+            event: { selector: '.timeline-event', required: true, minItems: 1 }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: 'components/interactive-timeline.css',
+    engagementTracking: 'viewAllTimelineEvents',
+    emitsEvents: ['timeline:event-viewed']
+};
+
+import { announceToScreenReader } from './index.js';
+import engagementManager from '../../engagement/engagement-manager.js';
+import * as NavigationState from '../../navigation/NavigationState.js';
+import { eventBus } from '../../core/event-bus.js';
+import { logger } from '../../utilities/logger.js';
+
+/**
+ * Initializes an interactive timeline component.
+ * @param {Element|string} root - The timeline container element or selector
+ * @param {object} options - Configuration options
+ * @param {string} options.mode - 'free' (any order) or 'sequential' (must view in order)
+ * @returns {object} API with activate, deactivate, destroy methods
+ */
+export function init(root, options = {}) {
+    const container = typeof root === 'string' ? document.querySelector(root) : root;
+    if (!container) {
+        logger.fatal('initInteractiveTimeline: container not found', { domain: 'ui', operation: 'initInteractiveTimeline' });
+        return;
+    }
+
+    const mode = options.mode || container.dataset.timelineMode || 'free';
+    const events = Array.from(container.querySelectorAll('.timeline-event'));
+
+    if (!events.length) {
+        logger.fatal('initInteractiveTimeline: no timeline events found', { domain: 'ui', operation: 'initInteractiveTimeline' });
+        return;
+    }
+
+    // Get current slide ID for engagement tracking
+    const currentSlideId = NavigationState.getCurrentSlideId();
+
+    // Register timeline events for engagement tracking
+    if (currentSlideId) {
+        const eventIds = events.map(ev => ev.dataset.eventId).filter(Boolean);
+        engagementManager.registerTimeline(currentSlideId, eventIds);
+    }
+
+    // Track which events have been viewed
+    const viewedEvents = new Set();
+    let lastViewedIndex = -1;
+
+    /**
+     * Expands a timeline event to show its details.
+     * @param {Element} event - The timeline event element
+     * @param {boolean} announce - Whether to announce to screen reader
+     */
+    function expandEvent(event, announce = true) {
+        const eventId = event.dataset.eventId;
+        const eventIndex = events.indexOf(event);
+
+        // In sequential mode, check if previous events are viewed
+        if (mode === 'sequential' && eventIndex > 0) {
+            const previousViewed = events.slice(0, eventIndex).every(
+                ev => viewedEvents.has(ev.dataset.eventId)
+            );
+            if (!previousViewed) {
+                announceToScreenReader('Please view previous events first', 'polite');
+                return;
+            }
+        }
+
+        // Collapse other events (single-expand behavior)
+        events.forEach(ev => {
+            if (ev !== event && ev.classList.contains('expanded')) {
+                ev.classList.remove('expanded');
+                ev.setAttribute('aria-expanded', 'false');
+            }
+        });
+
+        // Toggle this event
+        const isExpanding = !event.classList.contains('expanded');
+        event.classList.toggle('expanded');
+        event.setAttribute('aria-expanded', isExpanding ? 'true' : 'false');
+
+        if (isExpanding) {
+            // Track view
+            if (!viewedEvents.has(eventId)) {
+                viewedEvents.add(eventId);
+                lastViewedIndex = Math.max(lastViewedIndex, eventIndex);
+
+                // Track in engagement manager
+                if (currentSlideId && eventId) {
+                    engagementManager.trackTimelineView(currentSlideId, eventId);
+                }
+
+                // Emit event for other listeners
+                eventBus.emit('timeline:event-viewed', {
+                    timelineId: container.id || 'timeline',
+                    eventId,
+                    eventIndex,
+                    viewedCount: viewedEvents.size,
+                    totalEvents: events.length
+                });
+            }
+
+            // Update visual progress
+            updateProgress();
+
+            if (announce) {
+                const title = event.querySelector('h4, h3, .timeline-title')?.textContent || `Event ${eventIndex + 1}`;
+                announceToScreenReader(`Expanded: ${title}. ${viewedEvents.size} of ${events.length} events viewed.`);
+            }
+        }
+    }
+
+    /**
+     * Updates the progress indicator if present.
+     */
+    function updateProgress() {
+        const progressEl = container.querySelector('.timeline-progress');
+        if (progressEl) {
+            progressEl.textContent = `${viewedEvents.size} of ${events.length}`;
+            progressEl.setAttribute('aria-valuenow', viewedEvents.size);
+            progressEl.setAttribute('aria-valuemax', events.length);
+        }
+
+        // Update visual state of markers
+        events.forEach((ev, index) => {
+            const eventId = ev.dataset.eventId;
+            if (viewedEvents.has(eventId)) {
+                ev.classList.add('viewed');
+            }
+
+            // In sequential mode, mark locked events
+            if (mode === 'sequential') {
+                const isLocked = index > 0 && !events.slice(0, index).every(
+                    prev => viewedEvents.has(prev.dataset.eventId)
+                );
+                ev.classList.toggle('locked', isLocked);
+                ev.setAttribute('aria-disabled', isLocked ? 'true' : 'false');
+            }
+        });
+    }
+
+    /**
+     * Handles click events on timeline items.
+     */
+    function handleClick(e) {
+        const event = e.target.closest('.timeline-event');
+        if (event && events.includes(event)) {
+            e.preventDefault();
+            expandEvent(event);
+        }
+    }
+
+    /**
+     * Handles keyboard navigation.
+     */
+    function handleKeydown(e) {
+        const event = e.target.closest('.timeline-event');
+        if (!event || !events.includes(event)) return;
+
+        const currentIndex = events.indexOf(event);
+        let targetIndex = null;
+
+        switch (e.key) {
+            case 'ArrowDown':
+            case 'ArrowRight':
+                targetIndex = Math.min(currentIndex + 1, events.length - 1);
+                break;
+            case 'ArrowUp':
+            case 'ArrowLeft':
+                targetIndex = Math.max(currentIndex - 1, 0);
+                break;
+            case 'Home':
+                targetIndex = 0;
+                break;
+            case 'End':
+                targetIndex = events.length - 1;
+                break;
+            case 'Enter':
+            case ' ':
+                e.preventDefault();
+                expandEvent(event);
+                return;
+        }
+
+        if (targetIndex !== null && targetIndex !== currentIndex) {
+            e.preventDefault();
+            const targetEvent = events[targetIndex];
+            targetEvent.focus();
+        }
+    }
+
+    // Set up ARIA attributes
+    container.setAttribute('role', 'list');
+    container.setAttribute('aria-label', container.dataset.timelineLabel || 'Interactive timeline');
+
+    events.forEach((event, index) => {
+        event.setAttribute('role', 'listitem');
+        event.setAttribute('tabindex', index === 0 ? '0' : '-1');
+        event.setAttribute('aria-expanded', 'false');
+
+        // Ensure event has an ID for accessibility
+        if (!event.id && event.dataset.eventId) {
+            event.id = `timeline-event-${event.dataset.eventId}`;
+        }
+    });
+
+    // Add event listeners
+    container.addEventListener('click', handleClick);
+    container.addEventListener('keydown', handleKeydown);
+
+    // Initial progress update
+    updateProgress();
+
+    // Return API
+    return {
+        /**
+         * Expands a specific event by ID or index.
+         */
+        expandEvent(eventIdOrIndex) {
+            const event = typeof eventIdOrIndex === 'number'
+                ? events[eventIdOrIndex]
+                : events.find(ev => ev.dataset.eventId === eventIdOrIndex);
+            if (event) expandEvent(event);
+        },
+
+        /**
+         * Gets the current progress.
+         */
+        getProgress() {
+            return {
+                viewed: viewedEvents.size,
+                total: events.length,
+                percentage: Math.round((viewedEvents.size / events.length) * 100),
+                viewedIds: Array.from(viewedEvents)
+            };
+        },
+
+        /**
+         * Cleans up event listeners.
+         */
+        destroy() {
+            container.removeEventListener('click', handleClick);
+            container.removeEventListener('keydown', handleKeydown);
+        }
+    };
+}

package/framework/js/components/ui-components/intro-cards.js

@@ -0,0 +1,35 @@
+/**
+ * Intro Cards Layout Pattern
+ * 
+ * CSS-only component for introduction/overview slides.
+ */
+
+export const schema = {
+    type: 'intro-cards',
+    description: 'Introduction section with centered intro text and card grid',
+    example: `<div data-component="intro-cards">
+  <div class="intro"><h2>Welcome to Courseware</h2><p class="lead">Explore our key features below.</p></div>
+  <div class="card-grid">
+    <div class="card"><div class="card-body"><h3>Interactive</h3><p>Drag-drop, quizzes, and more.</p></div></div>
+    <div class="card"><div class="card-body"><h3>Accessible</h3><p>WCAG-compliant out of the box.</p></div></div>
+  </div>
+</div>`,
+    properties: {},
+    structure: {
+        container: '[data-component="intro-cards"]',
+        children: {
+            intro: { selector: '.intro' },
+            lead: { selector: '.intro .lead' },
+            cardGrid: { selector: '.card-grid', required: true }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssOnly: true,
+    cssFile: 'components/intro-cards.css'
+};
+
+/** No-op initializer — CSS-only component, registered for consistency. */
+export function init() {}