coursecode 0.1.0

package/framework/js/utilities/ui-initializer.js

@@ -0,0 +1,146 @@
+/**
+ * @file ui-initializer.js
+ * @description Automatically initializes UI components based on data-attributes.
+ * Uses the component catalog for dynamic discovery — no hardcoded component list.
+ */
+
+import { logger } from './logger.js';
+import { getComponentInit, getComponentStyles, isComponentRegistered, getRegisteredComponentTypes } from '../core/component-catalog.js';
+import { init as initNotificationTriggers } from '../components/ui-components/notifications.js';
+
+
+import engagementManager from '../engagement/engagement-manager.js';
+import * as NavigationState from '../navigation/NavigationState.js';
+
+// Track which custom component styles have been injected
+const injectedStyles = new Set();
+
+/**
+ * Inject custom component styles into the document head
+ * @param {string} type - Component type
+ * @param {string} styles - CSS string
+ */
+function injectStyles(type, styles) {
+    if (injectedStyles.has(type) || !styles) return;
+
+    const styleEl = document.createElement('style');
+    styleEl.setAttribute('data-component-styles', type);
+    styleEl.textContent = styles;
+    document.head.appendChild(styleEl);
+    injectedStyles.add(type);
+}
+
+/**
+ * Scans a container element for declarative UI components and initializes them.
+ * @param {HTMLElement} container - The container element to scan.
+ */
+export function initializeDeclarativeComponents(container) {
+    if (!container || typeof container.querySelectorAll !== 'function') {
+        return;
+    }
+
+    const components = container.querySelectorAll('[data-component]');
+
+    components.forEach(element => {
+        const componentName = element.dataset.component;
+
+        if (!isComponentRegistered(componentName)) {
+            logger.warn(`[UI-Initializer] Unknown component: '${componentName}'. Registered: ${getRegisteredComponentTypes().join(', ')}`);
+            return;
+        }
+
+        // Inject styles for custom components (CSS-in-JS)
+        const styles = getComponentStyles(componentName);
+        if (styles) {
+            injectStyles(componentName, styles);
+        }
+
+        // Get and call init function from catalog
+        const initializer = getComponentInit(componentName);
+        if (initializer && typeof initializer === 'function') {
+            try {
+                initializer(element);
+            } catch (error) {
+                logger.error(`[UI-Initializer] Failed to initialize '${componentName}' component: ${error.message}`, { domain: 'ui', operation: 'initializeComponent', stack: error.stack, component: componentName });
+            }
+        }
+        // CSS-only components (no init or no-op init) handled purely by CSS
+    });
+
+    // Tooltips auto-initialize via event delegation - no call needed
+
+    // Register all flip cards with engagement manager (batch registration like tabs)
+    // This must happen AFTER all flip cards are initialized
+    registerFlipCardsForEngagement(container);
+
+    // Register all modals with engagement manager (batch registration)
+    // This must happen AFTER all modal triggers are initialized
+    registerModalsForEngagement(container);
+
+    // Initialize declarative notification triggers (event delegation pattern)
+    initNotificationTriggers(container);
+
+
+    // Register lightbox triggers with engagement manager (batch registration)
+    // This must happen AFTER all lightbox triggers are initialized by the catalog
+    registerLightboxesForEngagement(container);
+}
+
+/**
+ * Registers all flip cards in the container with the engagement manager.
+ * This batch registration ensures flipCardsTotal is set correctly after all cards are found.
+ * @param {HTMLElement} container - The container to scan for flip cards
+ */
+function registerFlipCardsForEngagement(container) {
+    const flipCards = container.querySelectorAll('[data-component="flip-card"][data-flip-card-id]');
+    if (!flipCards.length) return;
+
+    const currentSlideId = NavigationState.getCurrentSlideId();
+    if (!currentSlideId) return;
+
+    const cardIds = Array.from(flipCards).map(card => card.dataset.flipCardId).filter(Boolean);
+    if (cardIds.length > 0) {
+        engagementManager.registerFlipCards(currentSlideId, cardIds);
+        logger.debug(`[UI-Initializer] Registered ${cardIds.length} flip cards for engagement tracking`);
+    }
+}
+
+/**
+ * Registers all modal triggers in the container with the engagement manager.
+ * This batch registration ensures modalsTotal is set correctly after all triggers are found.
+ * @param {HTMLElement} container - The container to scan for modal triggers
+ */
+function registerModalsForEngagement(container) {
+    const modalTriggers = container.querySelectorAll('[data-component="modal-trigger"][data-modal-id]');
+    if (!modalTriggers.length) return;
+
+    const currentSlideId = NavigationState.getCurrentSlideId();
+    if (!currentSlideId) return;
+
+    const modalIds = Array.from(modalTriggers).map(trigger => trigger.dataset.modalId).filter(Boolean);
+    if (modalIds.length > 0) {
+        engagementManager.registerModals(currentSlideId, modalIds);
+        logger.debug(`[UI-Initializer] Registered ${modalIds.length} modals for engagement tracking`);
+    }
+}
+
+/**
+ * Registers all lightbox triggers in the container with the engagement manager.
+ * This batch registration ensures lightboxesTotal is set correctly after all triggers are found.
+ * @param {HTMLElement} container - The container to scan for lightbox triggers
+ */
+function registerLightboxesForEngagement(container) {
+    const lightboxTriggers = container.querySelectorAll('[data-component="lightbox"]');
+    if (!lightboxTriggers.length) return;
+
+    const currentSlideId = NavigationState.getCurrentSlideId();
+    if (!currentSlideId) return;
+
+    const lightboxIds = Array.from(lightboxTriggers)
+        .map(trigger => trigger.id || trigger.dataset.lightboxId)
+        .filter(Boolean);
+    if (lightboxIds.length > 0) {
+        engagementManager.registerLightbox(currentSlideId, lightboxIds);
+        logger.debug(`[UI-Initializer] Registered ${lightboxIds.length} lightboxes for engagement tracking`);
+    }
+}

package/framework/js/utilities/utilities.js

@@ -0,0 +1,293 @@
+/**
+ * @file utilities.js
+ * @description Core utility functions for the SCORM framework.
+ * These are pure, stateless helper functions.
+ */
+
+/**
+ * Format duration in milliseconds to a human-readable string.
+ * @param {number} ms - Duration in milliseconds
+ * @returns {string} Formatted duration (e.g., "2m 30s")
+ */
+export function formatDuration(ms) {
+    if (!ms || ms < 0) {
+        return '0s';
+    }
+
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+
+    if (hours > 0) {
+        return `${hours}h ${minutes % 60}m`;
+    } else if (minutes > 0) {
+        return `${minutes}m ${seconds % 60}s`;
+    } else {
+        return `${seconds}s`;
+    }
+}
+
+/**
+ * Deep clone an object (handles primitives, arrays, objects, and Dates).
+ * @param {*} obj - Value to clone
+ * @returns {*} Cloned value
+ */
+export function deepClone(obj) {
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    if (obj instanceof Date) {
+        return new Date(obj.getTime());
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(item => deepClone(item));
+    }
+    
+    const clonedObj = {};
+    for (const key in obj) {
+        if (obj.hasOwnProperty(key)) {
+            clonedObj[key] = deepClone(obj[key]);
+        }
+    }
+    return clonedObj;
+}
+
+/**
+ * Generate a unique ID with optional prefix.
+ * @param {string} prefix - Optional prefix for the ID
+ * @returns {string} Unique ID (format: prefix-timestamp-random)
+ */
+export function generateId(prefix = 'id') {
+    return `${prefix}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Escape HTML entities in text.
+ * @param {string} text - Text to escape
+ * @returns {string} Text with HTML entities escaped
+ */
+export function escapeHTML(text) {
+    if (typeof text !== 'string') {
+        return '';
+    }
+    const map = {
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&#039;'
+    };
+    return text.replace(/[&<>"']/g, m => map[m]);
+}
+
+/**
+ * Check if an element is fully visible in the viewport.
+ * @param {HTMLElement} element - Element to check
+ * @returns {boolean} True if element is fully visible within viewport
+ */
+export function isElementVisible(element) {
+    if (!element || !(element instanceof HTMLElement)) {
+        return false;
+    }
+
+    const rect = element.getBoundingClientRect();
+    const viewportHeight = window.innerHeight || document.documentElement.clientHeight;
+    const viewportWidth = window.innerWidth || document.documentElement.clientWidth;
+
+    return (
+        rect.top >= 0 &&
+        rect.left >= 0 &&
+        rect.bottom <= viewportHeight &&
+        rect.right <= viewportWidth
+    );
+}
+
+/**
+ * Scroll element into view with smooth behavior.
+ * @param {HTMLElement} element - Element to scroll to
+ * @param {Object} options - ScrollIntoView options
+ */
+export function scrollToElement(element, options = {}) {
+    if (!element || !(element instanceof HTMLElement)) {
+        return;
+    }
+
+    const defaultOptions = {
+        behavior: 'smooth',
+        block: 'start',
+        inline: 'nearest'
+    };
+
+    element.scrollIntoView({ ...defaultOptions, ...options });
+}
+
+/**
+ * Get all focusable elements within a container.
+ * @param {HTMLElement} container - Container element
+ * @returns {Array<HTMLElement>} Array of focusable elements
+ */
+export function getFocusableElements(container) {
+    if (!container || !(container instanceof HTMLElement)) {
+        return [];
+    }
+
+    const selector = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+    return Array.from(container.querySelectorAll(selector));
+}
+
+/**
+ * Trap focus within a container (for modals, dialogs).
+ * Returns a cleanup function that must be called to remove the trap.
+ * @param {HTMLElement} container - Container to trap focus in
+ * @returns {Function} Cleanup function to remove trap
+ */
+export function trapFocus(container) {
+    if (!container || !(container instanceof HTMLElement)) {
+        throw new Error('trapFocus: container must be a valid HTMLElement');
+    }
+
+    const focusableElements = getFocusableElements(container);
+    if (focusableElements.length === 0) {
+        return () => { };
+    }
+
+    const firstElement = focusableElements[0];
+    const lastElement = focusableElements[focusableElements.length - 1];
+
+    const handleTabKey = (e) => {
+        if (e.key !== 'Tab') {
+            return;
+        }
+
+        if (e.shiftKey) {
+            if (document.activeElement === firstElement) {
+                e.preventDefault();
+                lastElement.focus();
+            }
+        } else {
+            if (document.activeElement === lastElement) {
+                e.preventDefault();
+                firstElement.focus();
+            }
+        }
+    };
+
+    container.addEventListener('keydown', handleTabKey);
+    firstElement.focus();
+
+    return () => {
+        container.removeEventListener('keydown', handleTabKey);
+    };
+}
+
+/**
+ * Format a number as a percentage string.
+ * @param {number} value - Value to format (0-1 if isDecimal=true, 0-100 if isDecimal=false)
+ * @param {boolean} isDecimal - True if value is 0-1, false if 0-100
+ * @returns {string} Formatted percentage (e.g., "75%")
+ */
+export function formatPercentage(value, isDecimal = true) {
+    if (typeof value !== 'number' || isNaN(value)) {
+        return '0%';
+    }
+    const percent = isDecimal ? value * 100 : value;
+    return `${Math.round(percent)}%`;
+}
+
+/**
+ * Wait for a condition to be true, checking at regular intervals.
+ * @param {Function} condition - Function that returns true when condition is met
+ * @param {number} timeout - Maximum time to wait in milliseconds
+ * @param {number} interval - Check interval in milliseconds
+ * @returns {Promise<void>} Resolves when condition is met, rejects on timeout
+ */
+export function waitFor(condition, timeout = 5000, interval = 100) {
+    if (!condition || typeof condition !== 'function') {
+        return Promise.reject(new Error('waitFor: condition must be a function'));
+    }
+    if (timeout <= 0) {
+        return Promise.reject(new Error('waitFor: timeout must be positive'));
+    }
+    if (interval <= 0) {
+        return Promise.reject(new Error('waitFor: interval must be positive'));
+    }
+
+    return new Promise((resolve, reject) => {
+        const startTime = Date.now();
+
+        const check = () => {
+            try {
+                if (condition()) {
+                    resolve();
+                } else if (Date.now() - startTime >= timeout) {
+                    reject(new Error('Timeout waiting for condition'));
+                } else {
+                    setTimeout(check, interval);
+                }
+            } catch (error) {
+                reject(new Error(`Condition check failed: ${error.message}`));
+            }
+        };
+
+        check();
+    });
+}
+
+/**
+ * Deep merge multiple objects (mutates target object).
+ * Plain objects are merged recursively; other values are overwritten.
+ * @param {Object} target - The target object to merge into (will be mutated)
+ * @param {...Object} sources - The source objects to merge from
+ * @returns {Object} The merged target object
+ */
+export function deepMerge(target, ...sources) {
+    if (!target || typeof target !== 'object' || Array.isArray(target)) {
+        throw new Error('deepMerge: target must be a plain object');
+    }
+
+    if (sources.length === 0) {
+        return target;
+    }
+
+    const source = sources.shift();
+
+    if (source && typeof source === 'object' && !Array.isArray(source)) {
+        for (const key in source) {
+            if (source.hasOwnProperty(key)) {
+                const sourceValue = source[key];
+                const targetValue = target[key];
+
+                if (sourceValue && typeof sourceValue === 'object' && !Array.isArray(sourceValue)) {
+                    // Recursive merge for plain objects
+                    if (!targetValue || typeof targetValue !== 'object' || Array.isArray(targetValue)) {
+                        target[key] = {};
+                    }
+                    deepMerge(target[key], sourceValue);
+                } else {
+                    // Direct assignment for primitives, arrays, and other types
+                    target[key] = sourceValue;
+                }
+            }
+        }
+    }
+
+    return deepMerge(target, ...sources);
+}
+
+/**
+ * Shuffle an array using Fisher-Yates algorithm (creates new array).
+ * @param {Array} array - Array to shuffle
+ * @returns {Array} New shuffled array
+ */
+export function shuffleArray(array) {
+    if (!Array.isArray(array)) {
+        throw new Error('shuffleArray: input must be an array');
+    }
+
+    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;
+}

package/framework/js/utilities/view-manager.js

@@ -0,0 +1,227 @@
+import { eventBus } from '../core/event-bus.js';
+import { logger } from './logger.js';
+import { validateRenderedHTML } from '../validation/html-validators.js';
+import { initializeDeclarativeComponents } from './ui-initializer.js';
+import { courseConfig } from '../../../course/course-config.js';
+
+/**
+ * Creates a view manager for a given container element.
+ * @param {HTMLElement} container - The container element for the views.
+ * @param {string} [scope='local'] - The scope of this ViewManager ('main' for main navigation, 'assessment' for assessment internal views, etc.)
+ * @returns {object} A view manager instance.
+ */
+export function createViewManager(container, scope = 'local') {
+    if (!container || !(container instanceof HTMLElement)) {
+        throw new Error('ViewManager: A valid container element is required.');
+    }
+
+    const views = {};
+    let currentViewName = null;
+
+    /**
+     * Registers a view with lifecycle hooks.
+     * @param {string} name - The name of the view.
+     * @param {object} viewObject - An object defining the view.
+     * @param {Function} viewObject.render - A function that returns an HTMLElement. Called every time the view is shown.
+     * @param {Function} [viewObject.onShow] - A function called every time the view is shown, after rendering.
+     * @param {Function} [viewObject.onHide] - A function called every time the view is hidden, before removal from DOM.
+     */
+    function registerView(name, viewObject) {
+        if (!name) {
+            throw new Error('ViewManager: View name is required.');
+        }
+        if (!viewObject || typeof viewObject.render !== 'function') {
+            throw new Error(`ViewManager: View '${name}' must be an object with a render function.`);
+        }
+        views[name] = { ...viewObject };
+    }
+
+    /**
+     * Shows a view by name.
+     * @param {string} name - The name of the view to show.
+     * @param {object} [options] - Options to pass to the render and onShow functions.
+     */
+    async function showView(name, options = {}) {
+        if (!views[name]) {
+            throw new Error(`ViewManager: View '${name}' not found.`);
+        }
+
+        // Hide the current view and call its onHide hook
+        let oldElement = null;
+        if (currentViewName && views[currentViewName]) {
+            const oldView = views[currentViewName];
+            // Get the current element from the container
+            oldElement = container.firstElementChild;
+            if (oldElement && typeof oldView.onHide === 'function') {
+                oldView.onHide(oldElement);
+            }
+        }
+
+        const newView = views[name];
+
+        // Emit before-change event to allow cleanup (e.g., clearing interaction registry)
+        // Include scope to distinguish main navigation from component-internal navigation
+        eventBus.emit('view:before-change', {
+            oldView: currentViewName,
+            newView: name,
+            scope: scope,
+            context: options
+        });
+
+        // Always render fresh to ensure current data is displayed
+        let newElement = await newView.render(options);
+
+        if (!(newElement instanceof HTMLElement)) {
+            throw new Error(`ViewManager: View '${name}' render function must return an HTMLElement.`);
+        }
+
+        // Auto-wrap content with content-width class if configured and not already wrapped
+        newElement = autoWrapContentIfNeeded(newElement, name);
+
+        // Validate rendered HTML for common issues BEFORE adding to DOM
+        validateRenderedContent(newElement, name);
+
+        // Clear container and add new view
+        container.innerHTML = '';
+        container.appendChild(newElement);
+
+        // Initialize any declarative components within the new view
+        initializeDeclarativeComponents(newElement);
+
+        // Call onShow hook
+        if (typeof newView.onShow === 'function') {
+            newView.onShow(newElement, options);
+        }
+
+        currentViewName = name;
+        eventBus.emit('view:change', { view: name, context: options });
+    }
+
+    /**
+     * Auto-wraps content with a content-width class if configured and not already wrapped.
+     * Allows per-slide override using data-content-width attribute.
+     * @param {HTMLElement} element - The rendered element
+     * @param {string} viewName - The name of the view being rendered
+     * @returns {HTMLElement} The element, potentially wrapped
+     * @private
+     */
+    function autoWrapContentIfNeeded(element, _viewName) {
+        // Canvas layout: author owns all styling, no auto-wrapping
+        if (courseConfig?.layout === 'canvas') {
+            return element;
+        }
+
+        // Check for per-slide override via data-content-width attribute
+        const dataAttrWidth = element.getAttribute('data-content-width');
+        const slideConfigWidth = dataAttrWidth;
+
+        // Determine which width to use: per-slide override > global config > no wrapping
+        const configWidth = slideConfigWidth || courseConfig?.slideDefaults?.contentWidth;
+        
+        if (!configWidth) {
+            // No wrapping configured
+            return element;
+        }
+
+        // Check if already wrapped with a content-width class
+        if (hasContentWidthClass(element)) {
+            // Already wrapped, don't double-wrap
+            return element;
+        }
+
+        // Create wrapper with appropriate content-width class
+        const wrapper = document.createElement('div');
+        wrapper.className = `content-${configWidth}`;
+        wrapper.appendChild(element);
+        return wrapper;
+    }
+
+    /**
+     * Checks if an element or its children already have a content-width class.
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if element or children have content-width class
+     * @private
+     */
+    function hasContentWidthClass(element) {
+        const contentWidthClasses = ['content-narrow', 'content-medium', 'content-wide', 'content-full'];
+        
+        // Check the element itself
+        if (element.classList && contentWidthClasses.some(cls => element.classList.contains(cls))) {
+            return true;
+        }
+        
+        // Check immediate children (common pattern: wrapper div around content)
+        if (element.children && element.children.length > 0) {
+            for (const child of element.children) {
+                if (child.classList && contentWidthClasses.some(cls => child.classList.contains(cls))) {
+                    return true;
+                }
+            }
+        }
+        
+        return false;
+    }
+
+    /**
+     * Validates rendered content for common issues that can cause page reloads or errors.
+     * @param {HTMLElement} element - The rendered element to validate
+     * @param {string} viewName - The name of the view being rendered
+     * @private
+     */
+    function validateRenderedContent(element, viewName) {
+        // Use centralized validation from html-validators.js
+        const validation = validateRenderedHTML(element, viewName);
+        
+        if (!validation.valid) {
+            // Process each error and emit events
+            validation.errors.forEach(error => {
+                const message = `View "${viewName}" [${error.type}]: ${error.message}`;
+                logger.error(`[ViewManager] ${message}`, { domain: 'view', operation: 'validateRenderedContent', ...error.context });
+            });
+
+            // Throw with a summary of all errors
+            const errorSummary = validation.errors.map(e => `[${e.type}] ${e.message}`).join('; ');
+            throw new Error(`[ViewManager] View "${viewName}" has ${validation.errors.length} validation error(s): ${errorSummary}`);
+        }
+    }
+
+    /**
+     * Gets the name of the currently visible view.
+     * @returns {string|null} The name of the current view.
+     */
+    function getCurrentView() {
+        return currentViewName;
+    }
+
+    /**
+     * Gets the container element.
+     * @returns {HTMLElement} The container element.
+     */
+    function getContainer() {
+        return container;
+    }
+
+    /**
+     * Destroys the view manager and cleans up the container.
+     */
+    function destroy() {
+        // Call onHide for current view if exists
+        if (currentViewName && views[currentViewName]) {
+            const currentElement = container.firstElementChild;
+            const currentView = views[currentViewName];
+            if (currentElement && typeof currentView.onHide === 'function') {
+                currentView.onHide(currentElement);
+            }
+        }
+        container.innerHTML = '';
+        currentViewName = null;
+    }
+
+    return {
+        registerView,
+        showView,
+        getCurrentView,
+        getContainer,
+        destroy,
+    };
+}