coursecode 0.1.0

package/framework/js/components/ui-components/modal.js

@@ -0,0 +1,386 @@
+/**
+ * @file modal.js
+ * @description Dynamic modal management system with audio support.
+ *
+ * Usage:
+ *   import * as Modal from './modal.js';
+ *
+ *   // In main application entry point:
+ *   Modal.setup();
+ *
+ *   // To show a modal:
+ *   Modal.show({
+ *     title: 'My Title',
+ *     body: '<p>My content.</p>',
+ *     footer: '<button data-action="close-modal">Close</button>',
+ *     config: { closeOnBackdrop: true, closeOnEscape: true },
+ *     audio: { 
+ *       src: 'audio/modal-narration.mp3', 
+ *       autoplay: true,
+ *       required: true,           // Audio must complete before modal counts as viewed
+ *       completionThreshold: 0.9  // 90% listened = complete
+ *     },
+ *     onOpen: () => console.log('Modal opened!'),
+ *     onClose: () => console.log('Modal closed!'),
+ *   });
+ * 
+ * Declarative Audio:
+ *   <button data-modal-trigger="my-modal" 
+ *           data-audio-src="audio/modal.mp3"
+ *           data-audio-required="true"
+ *           data-audio-threshold="0.9">
+ */
+
+import { iconManager } from '../../utilities/icons.js';
+import { announceToScreenReader } from './index.js';
+import { trapFocus } from '../../utilities/utilities.js';
+import audioManager from '../../managers/audio-manager.js';
+import engagementManager from '../../engagement/engagement-manager.js';
+import * as NavigationState from '../../navigation/NavigationState.js';
+import * as AudioPlayer from './audio-player.js';
+import { eventBus } from '../../core/event-bus.js';
+import { logger } from '../../utilities/logger.js';
+import { renderCompactPlayer } from './audio-player.js';
+
+// Schema for validation, linting, and AI-assisted authoring
+export const schema = {
+    type: 'modal-trigger',
+    description: 'Dynamic modal with audio support and focus trapping',
+    example: '<button data-component=\'modal-trigger\' data-title=\'Welcome\' data-body=\'<p>This modal supports rich content, audio narration, and focus trapping for accessibility.</p>\' class=\'btn btn-primary\'>Open Modal</button>',
+    properties: {
+        closeOnBackdrop: { type: 'boolean', default: true, description: 'Close when clicking backdrop' },
+        closeOnEscape: { type: 'boolean', default: true, description: 'Close on Escape key' },
+        hideCloseButton: { type: 'boolean', default: false, description: 'Hide the X close button' }
+    },
+    structure: {
+        trigger: '[data-modal-trigger], [data-component="modal-trigger"]',
+        modal: '#global-modal',
+        backdrop: '.modal-backdrop'
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: 'components/modals.css',
+    engagementTracking: 'viewAllModals',
+    emitsEvents: ['modal:opened', 'modal:closed']
+};
+
+let modalElement = null;
+let modalTitle = null;
+let modalBody = null;
+let modalFooter = null;
+let backdropElement = null;
+
+let activeConfig = {};
+let previousFocus = null;
+let isInitialized = false;
+let currentModalId = null; // Track current modal for audio completion
+let audioCompletedHandler = null; // Audio completion event handler
+let currentSlideId = null; // Track slide ID for engagement tracking
+
+/**
+ * Checks if the modal is currently visible.
+ * @returns {boolean}
+ */
+function isVisible() {
+    return modalElement && modalElement.classList.contains('active');
+}
+
+/**
+ * Initializes the modal system. Must be called once on app startup.
+ */
+export function setup() {
+    if (isInitialized) {
+        return;
+    }
+
+    modalElement = document.getElementById('global-modal');
+    backdropElement = document.querySelector('.modal-backdrop');
+
+    // Inject standard close icon
+    if (modalElement) {
+        const closeBtn = modalElement.querySelector('.modal-close');
+        if (closeBtn) {
+            closeBtn.innerHTML = iconManager.getIcon('x');
+        }
+    }
+
+    if (!modalElement || !backdropElement) {
+        logger.fatal('Modal elements (#global-modal, .modal-backdrop) not found in the DOM.', { domain: 'ui', operation: 'Modal.setup' });
+        return;
+    }
+
+    modalTitle = document.getElementById('global-modal-title');
+    modalBody = document.getElementById('global-modal-body');
+    modalFooter = document.getElementById('global-modal-footer');
+
+    // Close button handler (delegated to handle dynamic content)
+    modalElement.addEventListener('click', (event) => {
+        if (event.target.closest('[data-action="close-modal"]')) {
+            hide();
+        }
+    });
+
+    // Backdrop click handler
+    backdropElement.addEventListener('click', () => {
+        if (activeConfig.closeOnBackdrop) {
+            hide();
+        }
+    });
+
+    // Global Escape key handler
+    document.addEventListener('keydown', (e) => {
+        if (e.key === 'Escape' && isVisible() && activeConfig.closeOnEscape) {
+            hide();
+        }
+    });
+
+    isInitialized = true;
+}
+
+/**
+ * Initializes a single declarative modal trigger.
+ * @param {HTMLElement} trigger 
+ */
+export function init(trigger) {
+    trigger.addEventListener('click', () => {
+        const title = trigger.dataset.title || 'Modal';
+        let body = trigger.dataset.body || '';
+        let footer = trigger.dataset.footer || '<button class="btn btn-secondary" data-action="close-modal">Close</button>';
+
+        // If body/footer starts with #, try to find element and use its HTML
+        // Handle both regular elements and <template> elements
+        if (body.startsWith('#')) {
+            const el = document.querySelector(body);
+            if (el) {
+                if (el.tagName === 'TEMPLATE') {
+                    // For <template> elements, clone content and extract HTML
+                    const tempDiv = document.createElement('div');
+                    tempDiv.appendChild(el.content.cloneNode(true));
+                    body = tempDiv.innerHTML;
+                } else {
+                    body = el.innerHTML;
+                }
+            }
+        }
+        if (footer.startsWith('#')) {
+            const el = document.querySelector(footer);
+            if (el) {
+                if (el.tagName === 'TEMPLATE') {
+                    const tempDiv = document.createElement('div');
+                    tempDiv.appendChild(el.content.cloneNode(true));
+                    footer = tempDiv.innerHTML;
+                } else {
+                    footer = el.innerHTML;
+                }
+            }
+        }
+
+        // Check for audio configuration on trigger
+        const audioSrc = trigger.dataset.audioSrc;
+        const audioConfig = audioSrc ? {
+            src: audioSrc,
+            autoplay: trigger.dataset.audioAutoplay === 'true',
+            required: trigger.dataset.audioRequired === 'true',
+            completionThreshold: parseFloat(trigger.dataset.audioThreshold) || 0.95
+        } : null;
+
+        // Get modal ID for tracking (from trigger id or generate one)
+        const modalId = trigger.dataset.modalId || trigger.id || `modal-${Date.now()}`;
+
+        show({
+            title,
+            body,
+            footer,
+            audio: audioConfig,
+            modalId,
+            config: {
+                closeOnBackdrop: trigger.dataset.closeOnBackdrop !== 'false',
+                closeOnEscape: trigger.dataset.closeOnEscape !== 'false'
+            }
+        });
+    });
+}
+
+/**
+ * Shows the global modal with dynamic content.
+ * @param {object} options - The modal configuration.
+ * @param {string} options.title - The text for the modal title.
+ * @param {string} options.body - The HTML string for the modal body.
+ * @param {string} [options.footer] - The HTML string for the modal footer.
+ * @param {string} [options.modalId] - Unique identifier for this modal (for engagement tracking).
+ * @param {object} [options.config] - Behavior configuration.
+ * @param {boolean} [options.config.closeOnBackdrop=true] - If true, clicking the backdrop closes the modal.
+ * @param {boolean} [options.config.closeOnEscape=true] - If true, pressing Escape closes the modal.
+ * @param {boolean} [options.config.hideCloseButton=false] - If true, hides the modal's close (X) button.
+ * @param {object} [options.audio] - Audio configuration for modal narration.
+ * @param {string} options.audio.src - Audio file source path.
+ * @param {boolean} [options.audio.autoplay=true] - Whether to autoplay the audio.
+ * @param {boolean} [options.audio.required=false] - Whether audio must complete for modal engagement.
+ * @param {number} [options.audio.completionThreshold=0.95] - Percentage (0-1) for completion.
+ * @param {Function} [options.onOpen] - Callback executed when the modal opens.
+ * @param {Function} [options.onClose] - Callback executed when the modal closes.
+ */
+export async function show({ title, body, footer = '', modalId = null, config = {}, audio = null, onOpen, onClose }) {
+    if (!isInitialized) {
+        throw new Error('Modal system not initialized. Call setup() first.');
+    }
+
+    // Generate modal ID if not provided
+    currentModalId = modalId || `modal-${Date.now()}`;
+
+    // Store config for this active session
+    activeConfig = {
+        closeOnBackdrop: config.closeOnBackdrop !== false,
+        closeOnEscape: config.closeOnEscape !== false,
+        hideCloseButton: config.hideCloseButton === true,
+        audio,
+        modalId: currentModalId,
+        onOpen,
+        onClose,
+    };
+
+    // Show/hide the close button based on config
+    const closeBtn = modalElement.querySelector('.modal-close');
+    if (closeBtn) {
+        closeBtn.style.display = activeConfig.hideCloseButton ? 'none' : '';
+    }
+
+    // Populate content
+    modalTitle.textContent = title;
+    modalBody.innerHTML = body;
+
+    // If audio is present, prepend compact audio player to footer
+    if (audio && audio.src) {
+        const compactAudioHtml = renderCompactPlayer();
+        modalFooter.innerHTML = compactAudioHtml + footer;
+    } else {
+        modalFooter.innerHTML = footer;
+    }
+
+    // Save current focus
+    previousFocus = document.activeElement;
+
+    // Save the current slide ID (for engagement tracking)
+    currentSlideId = NavigationState.getCurrentSlideId();
+
+    // Track modal view for engagement (if this modal is registered for tracking)
+    if (currentSlideId && currentModalId) {
+        engagementManager.trackModalView(currentSlideId, currentModalId);
+    }
+
+    // Handle audio: load modal audio
+    // Note: Due to singleton audio element, slide audio and modal audio are mutually exclusive
+    // (enforced by runtime-linter - a slide cannot have both)
+    if (audioManager.isReady() && audio && audio.src) {
+        const audioContextId = `modal-${currentModalId}`;
+        try {
+            await audioManager.load({
+                src: audio.src,
+                autoplay: audio.autoplay === true,
+                required: audio.required || false,
+                completionThreshold: audio.completionThreshold || 0.95
+            }, audioContextId, 'modal');
+
+            logger.debug(`[Modal] Loaded modal audio: ${audioContextId}`);
+
+            // Initialize event listeners AFTER audio is loaded
+            if (modalFooter) {
+                AudioPlayer.initAudioControlsInContainer(modalFooter);
+            }
+        } catch (err) {
+            logger.warn('[Modal] Failed to load modal audio:', err.message);
+        }
+
+        // If audio is required, listen for completion
+        if (audio.required) {
+            audioCompletedHandler = ({ contextId }) => {
+                if (contextId === audioContextId && currentSlideId) {
+                    engagementManager.trackModalAudioComplete(currentSlideId, currentModalId);
+                }
+            };
+            eventBus.on('audio:completed', audioCompletedHandler);
+        }
+    }
+
+    // Show modal and backdrop
+    backdropElement.classList.add('active');
+    modalElement.classList.add('active');
+    modalElement.setAttribute('aria-hidden', 'false');
+
+    // Focus first focusable element
+    setTimeout(() => {
+        const focusable = modalElement.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
+        if (focusable.length > 0) {
+            focusable[0].focus();
+        }
+    }, 100);
+
+    // Setup focus trap
+    modalElement._focusTrapCleanup = trapFocus(modalElement);
+
+    if (activeConfig.onOpen) {
+        activeConfig.onOpen(modalElement);
+    }
+
+    announceToScreenReader(`Modal opened: ${title}`);
+}
+
+/**
+ * Hides the global modal.
+ */
+export function hide() {
+    if (!isInitialized || !modalElement.classList.contains('active')) {
+        return;
+    }
+
+    modalElement.classList.remove('active');
+    modalElement.setAttribute('aria-hidden', 'true');
+    backdropElement.classList.remove('active');
+
+    // Clean up focus trap
+    if (modalElement._focusTrapCleanup && typeof modalElement._focusTrapCleanup === 'function') {
+        modalElement._focusTrapCleanup();
+        modalElement._focusTrapCleanup = null;
+    }
+
+    // Clean up audio completion listener
+    if (audioCompletedHandler) {
+        eventBus.off('audio:completed', audioCompletedHandler);
+        audioCompletedHandler = null;
+    }
+
+    // Clean up audio state update listeners from modal footer
+    if (modalFooter._audioStateUpdateCleanup && typeof modalFooter._audioStateUpdateCleanup === 'function') {
+        modalFooter._audioStateUpdateCleanup();
+        modalFooter._audioStateUpdateCleanup = null;
+    }
+
+    // Handle audio: unload modal audio
+    // Note: No slide audio to restore (they're mutually exclusive, enforced by runtime-linter)
+    if (audioManager.isReady() && activeConfig.audio) {
+        audioManager.unload();
+        logger.debug('[Modal] Unloaded modal audio');
+    }
+
+    // Restore focus
+    if (previousFocus) {
+        previousFocus.focus();
+        previousFocus = null;
+    }
+
+    // Fire onClose callback
+    if (activeConfig.onClose) {
+        activeConfig.onClose(modalElement);
+    }
+
+    // Clear content and config for next use
+    modalTitle.textContent = '';
+    modalBody.innerHTML = '';
+    modalFooter.innerHTML = '';
+    currentModalId = null;
+    activeConfig = {};
+
+    announceToScreenReader('Modal closed');
+}

package/framework/js/components/ui-components/notifications.js

@@ -0,0 +1,145 @@
+/**
+ * @file notifications.js
+ * @description Notification system with event delegation.
+ */
+
+export const schema = {
+    type: 'notification-trigger',
+    description: 'Declarative notification trigger',
+    example: `<button data-action="show-notification" data-type="success" data-message="Your progress has been saved!" class="btn btn-primary" style="margin-right: 8px;">Success</button>
+<button data-action="show-notification" data-type="warning" data-message="You have unsaved changes." class="btn btn-secondary" style="margin-right: 8px;">Warning</button>
+<button data-action="show-notification" data-type="error" data-message="Connection lost. Please try again." class="btn btn-secondary">Error</button>`,
+    properties: {
+        type: { type: 'string', enum: ['info', 'success', 'warning', 'error'], default: 'info', dataAttribute: 'data-type' },
+        message: { type: 'string', required: true, dataAttribute: 'data-message' }
+    },
+    structure: {
+        container: '[data-action="show-notification"]',
+        children: {}
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: 'components/notifications.css',
+    engagementTracking: null,
+    emitsEvents: []
+};
+
+import { announceToScreenReader } from './index.js';
+import { logger } from '../../utilities/logger.js';
+
+let notificationContainer = null;
+let notificationId = 0;
+let initialized = false;
+
+export function setup() {
+    if (initialized) return;
+
+    notificationContainer = document.getElementById('notification-container');
+    if (!notificationContainer) {
+        logger.fatal('Notification container with ID "notification-container" not found in DOM.', { domain: 'ui', operation: 'Notifications.setup' });
+        return;
+    }
+
+    // Add a single, permanent delegated click listener
+    notificationContainer.addEventListener('click', (event) => {
+        const closeButton = event.target.closest('[data-action="dismiss-notification"]');
+        if (closeButton) {
+            const notification = closeButton.closest('.notification');
+            if (notification) {
+                dismissNotification(notification.id);
+            }
+        }
+    });
+
+    initialized = true;
+}
+
+/**
+ * Initializes declarative notification triggers in a container using event delegation.
+ * @param {HTMLElement} container
+ */
+export function init(container) {
+    // Use event delegation to handle dynamically rendered content
+    container.addEventListener('click', (event) => {
+        const trigger = event.target.closest('[data-action="show-notification"]');
+        if (trigger) {
+            const type = trigger.dataset.type || 'info';
+            const message = trigger.dataset.message || 'Notification';
+            showNotification(message, type);
+        }
+    });
+}
+
+export function showNotification(message, type = 'info', duration = 5000, options = {}) {
+    if (!initialized) {
+        setup();
+    }
+
+    if (!message || typeof message !== 'string') {
+        throw new Error('Notification message must be a non-empty string');
+    }
+
+    const id = `notification-${++notificationId}`;
+    const notification = document.createElement('div');
+
+    notification.id = id;
+    notification.className = `notification notification-${type}`;
+    notification.setAttribute('role', type === 'error' ? 'alert' : 'status');
+    notification.setAttribute('data-testid', `notification-${type}`);
+
+    const dismissible = options.dismissible !== false;
+    const closeButton = dismissible ? `
+        <button class="notification-close" data-action="dismiss-notification" aria-label="Close notification" data-testid="notification-close">×</button>
+    ` : '';
+
+    notification.innerHTML = `
+        <span class="notification-message">${message}</span>
+        ${closeButton}
+    `;
+
+    notificationContainer.appendChild(notification);
+
+    if (duration > 0) {
+        setTimeout(() => dismissNotification(id), duration);
+    }
+
+    announceToScreenReader(message, type === 'error' ? 'assertive' : 'polite');
+
+    return id;
+}
+
+export function dismissNotification(id) {
+  const notification = document.getElementById(id);
+  if (!notification) return;
+
+  notification.style.animation = 'notificationSlideOut 0.3s ease-out forwards';
+  setTimeout(() => {
+    if (notification.parentNode) {
+      notification.parentNode.removeChild(notification);
+    }
+  }, 300);
+}
+
+export function clearAllNotifications() {
+  if (!notificationContainer) return;
+  const notifications = notificationContainer.querySelectorAll('.notification');
+  notifications.forEach(notification => dismissNotification(notification.id));
+}
+
+export function showSuccess(message, duration = 4000, options = {}) {
+  return showNotification(message, 'success', duration, options);
+}
+
+export function showWarning(message, duration = 6000, options = {}) {
+  return showNotification(message, 'warning', duration, options);
+}
+
+export function showError(message, duration = 8000, options = {}) {
+  return showNotification(message, 'error', duration, options);
+}
+
+export function showInfo(message, duration = 5000, options = {}) {
+  return showNotification(message, 'info', duration, options);
+}

package/framework/js/components/ui-components/progress.js

@@ -0,0 +1,88 @@
+/**
+ * @file progress.js
+ * @description Handles progress bar components.
+ *
+ * Usage (Declarative):
+ * <div class="progress-bar" data-component="progress" id="my-progress" data-initial-value="25">
+ *   <div class="progress-bar-fill"></div>
+ *   <span class="progress-bar-text">25%</span>
+ * </div>
+ *
+ * Usage (Imperative):
+ * import { updateProgress } from '...';
+ * updateProgress('my-progress', 50);
+ */
+
+export const schema = {
+    type: 'progress',
+    description: 'Animated progress bar with percentage display',
+    example: `<div class="progress-bar" data-component="progress" id="preview-progress" data-initial-value="65">
+  <div class="progress-bar-fill" style="width: 65%"></div>
+  <span class="progress-bar-text">65%</span>
+</div>`,
+    properties: {
+        initialValue: { type: 'number', default: 0, dataAttribute: 'data-initial-value' }
+    },
+    structure: {
+        container: '[data-component="progress"]',
+        children: {
+            fill: { selector: '.progress-bar-fill', required: true },
+            text: { selector: '.progress-bar-text', required: false }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: 'components/engagement.css',
+    engagementTracking: null,
+    emitsEvents: []
+};
+
+/**
+ * Sets the value of a progress bar.
+ * @param {HTMLElement|string} elementOrId - The progress bar container element or its ID.
+ * @param {number} value - The progress value (0-100).
+ */
+import { logger } from '../../utilities/logger.js';
+
+export function updateProgress(elementOrId, value) {
+    const element = typeof elementOrId === 'string' ? document.getElementById(elementOrId) : elementOrId;
+    if (!element) {
+        logger.error('updateProgress: Element not found.', elementOrId);
+        return;
+    }
+
+    const fill = element.querySelector('.progress-bar-fill');
+    const text = element.querySelector('.progress-bar-text');
+    const clampedValue = Math.max(0, Math.min(100, value));
+
+    element.style.setProperty('--progress-percent', `${clampedValue}%`);
+    element.setAttribute('aria-valuenow', clampedValue);
+
+    if (fill) {
+        fill.style.width = `${clampedValue}%`;
+    }
+    if (text) {
+        text.textContent = `${Math.round(clampedValue)}%`;
+    }
+}
+
+/**
+ * Initializes a progress bar component, setting its initial value.
+ * @param {HTMLElement} element - The progress bar container element.
+ */
+export function init(element) {
+    if (!element) {
+        logger.fatal('initProgress: element not found.', { domain: 'ui', operation: 'initProgress' });
+        return;
+    }
+
+    const initialValue = parseFloat(element.dataset.initialValue) || 0;
+    updateProgress(element, initialValue);
+
+    return {
+        update: (value) => updateProgress(element, value),
+        destroy: () => {} // No listeners to remove
+    };
+}

package/framework/js/components/ui-components/quote.js

@@ -0,0 +1,41 @@
+/**
+ * Quote/Testimonial Layout Pattern
+ * 
+ * CSS-only component for customer quotes, testimonials, citations.
+ */
+
+export const schema = {
+    type: 'quote',
+    description: 'Quote/testimonial display with attribution',
+    example: `<div data-component="quote">
+  <p class="quote-text">"This framework has transformed how we create training content. It's intuitive, powerful, and makes our courses look professional."</p>
+  <div class="quote-attribution"><span class="quote-author">Jane Smith</span><span class="quote-role">Director of Training</span></div>
+</div>`,
+    properties: {
+        variant: {
+            type: 'string',
+            enum: ['default', 'card', 'accent', 'featured', 'dark'],
+            default: 'default',
+            description: 'Visual style variant (add as class, e.g., quote-card)'
+        }
+    },
+    structure: {
+        container: '[data-component="quote"]',
+        children: {
+            text: { selector: '.quote-text', required: true },
+            attribution: { selector: '.quote-attribution' },
+            avatar: { selector: '.quote-avatar' },
+            author: { selector: '.quote-author' },
+            role: { selector: '.quote-role' }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssOnly: true,
+    cssFile: 'components/quote.css'
+};
+
+/** No-op initializer — CSS-only component, registered for consistency. */
+export function init() {}

package/framework/js/components/ui-components/stats.js

@@ -0,0 +1,33 @@
+/**
+ * Stats/Metrics Layout Pattern
+ * 
+ * CSS-only component for displaying important numbers/statistics.
+ */
+
+export const schema = {
+    type: 'stats',
+    description: 'Statistics/metrics display with large numbers',
+    example: `<div data-component="stats">
+  <div class="stat"><span class="stat-value">150+</span><span class="stat-label">Active Courses</span></div>
+  <div class="stat"><span class="stat-value">98%</span><span class="stat-label">Completion Rate</span></div>
+  <div class="stat"><span class="stat-value">4.9</span><span class="stat-label">Average Rating</span></div>
+</div>`,
+    properties: {},
+    structure: {
+        container: '[data-component="stats"]',
+        children: {
+            stat: { selector: '.stat', required: true, minItems: 1 },
+            value: { selector: '.stat-value', parent: '.stat', required: true },
+            label: { selector: '.stat-label', parent: '.stat' }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssOnly: true,
+    cssFile: 'components/stats.css'
+};
+
+/** No-op initializer — CSS-only component, registered for consistency. */
+export function init() {}