coursecode 0.1.0

package/framework/js/components/ui-components/embed-frame.js

@@ -0,0 +1,274 @@
+/**
+ * @file embed-frame.js
+ * @description Sandboxed iframe component for embedding custom HTML/JS apps.
+ * 
+ * Provides CSS isolation and JS sandboxing for custom interactive elements.
+ * Communicates with the parent frame via postMessage for state persistence
+ * and engagement tracking.
+ *
+ * Usage (Declarative):
+ * <div data-component="embed-frame"
+ *      data-src="assets/widgets/my-app.html"
+ *      data-embed-id="custom-widget"
+ *      data-aspect-ratio="16/9">
+ * </div>
+ *
+ * PostMessage API (from embedded content):
+ * // Set a flag (triggers engagement re-evaluation)
+ * parent.postMessage({ type: 'coursecode:flag', key: 'widget-complete', value: true }, '*');
+ * 
+ * // Request resize (auto-height mode)
+ * parent.postMessage({ type: 'coursecode:resize', height: 400 }, '*');
+ * 
+ * // Log a message to the console (for debugging)
+ * parent.postMessage({ type: 'coursecode:log', level: 'info', message: 'Widget initialized' }, '*');
+ */
+
+export const schema = {
+    type: 'embed-frame',
+    description: 'Sandboxed iframe for custom HTML/JS apps',
+    example: `<div data-component="embed-frame" data-src="widgets/my-app.html" data-embed-id="custom-widget" data-aspect-ratio="16/9">
+  <p style="color: #64748b; font-size: 0.875rem; font-style: italic;">📦 Sandboxed iframe renders dynamically — embeds custom HTML/JS with postMessage API.</p>
+</div>`,
+    properties: {
+        src: { type: 'string', required: true, dataAttribute: 'data-src' },
+        embedId: { type: 'string', required: true, dataAttribute: 'data-embed-id' },
+        aspectRatio: { type: 'string', dataAttribute: 'data-aspect-ratio' }
+    },
+    structure: {
+        container: '[data-component="embed-frame"]',
+        children: {}  // Content is dynamically rendered
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: 'components/embed-frame.css',
+    engagementTracking: null,
+    emitsEvents: ['embed-frame:initialized', 'embed-frame:ready', 'embed-frame:flag']
+};
+
+import { logger } from '../../utilities/logger.js';
+import { eventBus } from '../../core/event-bus.js';
+import flagManager from '../../managers/flag-manager.js';
+
+/**
+ * Initializes an embed-frame component.
+ * @param {HTMLElement} container - The container element with data-component="embed-frame"
+ */
+export function init(container) {
+    if (!container) {
+        logger.fatal('initEmbedFrame: container not found.', { domain: 'ui', operation: 'initEmbedFrame' });
+        return;
+    }
+
+    const src = container.dataset.src;
+    const embedId = container.dataset.embedId;
+    const aspectRatio = container.dataset.aspectRatio || null;
+
+    if (!src) {
+        logger.fatal('initEmbedFrame: data-src attribute is required.', { domain: 'ui', operation: 'initEmbedFrame' });
+        return;
+    }
+
+    if (!embedId) {
+        logger.fatal('initEmbedFrame: data-embed-id attribute is required.', { domain: 'ui', operation: 'initEmbedFrame' });
+        return;
+    }
+
+    // Mark as initialized
+    if (container.dataset.embedInitialized === 'true') {
+        logger.debug('[EmbedFrame] Already initialized:', embedId);
+        return { destroy: () => { } };
+    }
+    container.dataset.embedInitialized = 'true';
+
+    // Build the iframe
+    const wrapper = document.createElement('div');
+    wrapper.className = 'embed-frame-wrapper';
+
+    if (aspectRatio) {
+        wrapper.style.aspectRatio = aspectRatio;
+    }
+
+    const iframe = document.createElement('iframe');
+    iframe.className = 'embed-frame-iframe';
+    iframe.src = _resolvePath(src);
+    // SECURITY NOTE: 'allow-same-origin' is required for postMessage to work reliably
+    // when the embedded widget is loaded from the same origin (local assets).
+    // Without it, the iframe gets an opaque origin ('null') which breaks postMessage
+    // in some browsers. The trade-off is that same-origin iframes CAN access the
+    // parent's DOM, cookies, and localStorage. This is acceptable because:
+    //   1. embed-frame is for author-controlled widgets, not untrusted user content
+    //   2. We validate event.source to ensure messages come from the correct iframe
+    //   3. For untrusted content, authors should use an external URL (cross-origin)
+    iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-forms');
+    iframe.setAttribute('loading', 'lazy');
+    iframe.setAttribute('title', `Embedded content: ${embedId}`);
+    iframe.setAttribute('data-testid', `embed-frame-${embedId}`);
+
+    // For auto-height mode (no aspect ratio)
+    if (!aspectRatio) {
+        wrapper.classList.add('embed-frame-auto-height');
+    }
+
+    wrapper.appendChild(iframe);
+    container.appendChild(wrapper);
+
+    // Message handler for postMessage communication
+    const messageHandler = (event) => {
+        // Validate the message came from this iframe
+        if (event.source !== iframe.contentWindow) {
+            return;
+        }
+
+        const data = event.data;
+        if (!data || typeof data !== 'object' || !data.type) {
+            return;
+        }
+
+        // Only handle coursecode: prefixed messages
+        if (!data.type.startsWith('coursecode:')) {
+            return;
+        }
+
+        const action = data.type.replace('coursecode:', '');
+
+        switch (action) {
+            case 'flag':
+                handleFlagMessage(data, embedId);
+                break;
+            case 'resize':
+                handleResizeMessage(data, wrapper, aspectRatio);
+                break;
+            case 'log':
+                handleLogMessage(data, embedId);
+                break;
+            case 'ready':
+                handleReadyMessage(embedId);
+                break;
+            default:
+                logger.warn(`[EmbedFrame] Unknown message type: ${data.type}`, { embedId });
+        }
+    };
+
+    window.addEventListener('message', messageHandler);
+
+    // Emit initialization event
+    eventBus.emit('embed-frame:initialized', { embedId, src });
+    logger.debug('[EmbedFrame] Initialized:', { embedId, src, aspectRatio });
+
+    return {
+        destroy: () => {
+            window.removeEventListener('message', messageHandler);
+            logger.debug('[EmbedFrame] Destroyed:', embedId);
+        }
+    };
+}
+
+/**
+ * Handles flag messages from embedded content.
+ * @param {object} data - Message data with key and value
+ * @param {string} embedId - The embed ID for logging
+ */
+function handleFlagMessage(data, embedId) {
+    const { key, value } = data;
+
+    if (typeof key !== 'string' || key.trim() === '') {
+        logger.error('[EmbedFrame] Invalid flag key:', { embedId, key });
+        return;
+    }
+
+    try {
+        flagManager.setFlag(key, value);
+        logger.debug('[EmbedFrame] Flag set via postMessage:', { embedId, key, value });
+        eventBus.emit('embed-frame:flag', { embedId, key, value });
+    } catch (error) {
+        logger.error('[EmbedFrame] Failed to set flag:', { embedId, key, error: error.message });
+    }
+}
+
+/**
+ * Handles resize messages from embedded content (auto-height mode).
+ * @param {object} data - Message data with height
+ * @param {HTMLElement} wrapper - The wrapper element
+ * @param {string|null} aspectRatio - The configured aspect ratio
+ */
+function handleResizeMessage(data, wrapper, aspectRatio) {
+    // Only allow resize in auto-height mode
+    if (aspectRatio) {
+        logger.warn('[EmbedFrame] Resize ignored - aspect ratio is fixed');
+        return;
+    }
+
+    const { height } = data;
+    if (typeof height !== 'number' || height < 50 || height > 5000) {
+        logger.warn('[EmbedFrame] Invalid resize height:', height);
+        return;
+    }
+
+    wrapper.style.height = `${height}px`;
+    logger.debug('[EmbedFrame] Resized to:', height);
+}
+
+/**
+ * Handles log messages from embedded content.
+ * @param {object} data - Message data with level and message
+ * @param {string} embedId - The embed ID for context
+ */
+function handleLogMessage(data, embedId) {
+    const { level = 'info', message } = data;
+    const prefix = `[EmbedFrame:${embedId}]`;
+
+    switch (level) {
+        case 'debug':
+            logger.debug(prefix, message);
+            break;
+        case 'info':
+            logger.info(prefix, message);
+            break;
+        case 'warn':
+            logger.warn(prefix, message);
+            break;
+        case 'error':
+            logger.error(prefix, message);
+            break;
+        default:
+            logger.info(prefix, message);
+    }
+}
+
+/**
+ * Handles ready messages from embedded content.
+ * @param {string} embedId - The embed ID
+ */
+function handleReadyMessage(embedId) {
+    logger.debug('[EmbedFrame] Embed ready:', embedId);
+    eventBus.emit('embed-frame:ready', { embedId });
+}
+
+/**
+ * Resolves embed path relative to course/assets/.
+ * Follows the same pattern as audio-manager and video-player.
+ * @param {string} src - The source path
+ * @returns {string} Resolved path
+ */
+function _resolvePath(src) {
+    // Already absolute URL or protocol-relative
+    if (src.startsWith('http://') || src.startsWith('https://') || src.startsWith('//')) {
+        return src;
+    }
+
+    // Already has leading slash (absolute path from root)
+    if (src.startsWith('/')) {
+        return src;
+    }
+
+    // Already uses ./ or ../ relative paths
+    if (src.startsWith('./') || src.startsWith('../')) {
+        return src;
+    }
+
+    // Otherwise, assume relative to course/assets/
+    return `./course/${src}`;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Features Layout Pattern
+ * 
+ * CSS-only component for highlighting 3-4 key features with icons.
+ */
+
+export const schema = {
+    type: 'features',
+    description: 'Feature showcase with icons and centered layout',
+    example: `<div data-component="features">
+  <div class="feature-item"><div class="feature-icon">🚀</div><h3>Fast</h3><p>Lightning-fast performance for all operations.</p></div>
+  <div class="feature-item"><div class="feature-icon">🔒</div><h3>Secure</h3><p>Built with security best practices.</p></div>
+  <div class="feature-item"><div class="feature-icon">🎨</div><h3>Flexible</h3><p>Customize everything to your needs.</p></div>
+</div>`,
+    properties: {},
+    structure: {
+        container: '[data-component="features"]',
+        children: {
+            item: { selector: '.feature-item', required: true, minItems: 1 },
+            icon: { selector: '.feature-icon', parent: '.feature-item' },
+            title: { selector: 'h3', parent: '.feature-item' }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssOnly: true,
+    cssFile: 'components/features.css'
+};
+
+/** No-op initializer — CSS-only component, registered for consistency. */
+export function init() {}

package/framework/js/components/ui-components/flip-card.js

@@ -0,0 +1,230 @@
+/**
+ * @file flip-card.js
+ * @description Flip card component with accessibility and engagement tracking.
+ * 
+ * Usage:
+ *   <div class="flip-card" data-component="flip-card" data-flip-card-id="card-1">
+ *     <div class="flip-card-inner">
+ *       <div class="flip-card-front">Front Content</div>
+ *       <div class="flip-card-back">Back Content</div>
+ *     </div>
+ *   </div>
+ * 
+ * For engagement tracking, use the viewAllFlipCards requirement:
+ *   engagement: {
+ *     required: true,
+ *     requirements: [{ type: 'viewAllFlipCards' }]
+ *   }
+ * 
+ * Each flip card must have a unique data-flip-card-id attribute for tracking.
+ */
+
+export const schema = {
+    type: 'flip-card',
+    description: 'Interactive flip card with front/back content',
+    example: `<div style="display: grid; grid-template-columns: repeat(2, 1fr); gap: 16px;">
+  <div class="flip-card" data-component="flip-card">
+    <div class="flip-card-inner">
+      <div class="flip-card-front"><span class="flip-card-icon">🎯</span><h3 class="flip-card-title">Click to Flip</h3><p class="text-sm text-muted">Front side</p></div>
+      <div class="flip-card-back"><h3 class="flip-card-title">Answer</h3><p class="flip-card-text">This is the back side content.</p></div>
+    </div>
+  </div>
+  <div class="flip-card" data-component="flip-card">
+    <div class="flip-card-inner">
+      <div class="flip-card-front"><span class="flip-card-icon">💡</span><h3 class="flip-card-title">Key Concept</h3><p class="text-sm text-muted">Click to reveal</p></div>
+      <div class="flip-card-back bg-secondary"><h3 class="flip-card-title">Definition</h3><p class="flip-card-text">The concept explained in detail.</p></div>
+    </div>
+  </div>
+</div>`,
+    properties: {
+        flipCardId: { type: 'string', required: true, dataAttribute: 'data-flip-card-id' }
+    },
+    structure: {
+        container: '[data-component="flip-card"]',
+        children: {
+            inner: { selector: '.flip-card-inner', required: true },
+            front: { selector: '.flip-card-front', required: true },
+            back: { selector: '.flip-card-back', required: true }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: 'components/flip-cards.css',
+    engagementTracking: 'viewAllFlipCards',
+    emitsEvents: ['flipcard:flipped']
+};
+
+import engagementManager from '../../engagement/engagement-manager.js';
+import * as NavigationState from '../../navigation/NavigationState.js';
+import { announceToScreenReader } from './index.js';
+import { logger } from '../../utilities/logger.js';
+
+/**
+ * Initializes all flip card components within a container.
+ * Call this once per slide to register all flip cards for engagement tracking.
+ * 
+ * @param {HTMLElement|string} root - Container element or selector
+ * @returns {Object} API for controlling flip cards
+ */
+export function initFlipCards(root) {
+    const container = typeof root === 'string' ? document.querySelector(root) : root;
+    if (!container) {
+        logger.fatal('UIComponents.initFlipCards: container not found', { domain: 'ui', operation: 'initFlipCards' });
+        return;
+    }
+
+    const flipCards = Array.from(container.querySelectorAll('[data-component="flip-card"], .flip-card'));
+    
+    if (flipCards.length === 0) {
+        logger.debug('[FlipCards] No flip cards found in container');
+        return { destroy: () => {} };
+    }
+
+    // Validate: All flip cards should have unique IDs for tracking
+    const cardIds = [];
+    const errors = [];
+    
+    flipCards.forEach((card, index) => {
+        const cardId = card.dataset.flipCardId;
+        if (!cardId) {
+            errors.push(`Flip card ${index + 1} is missing data-flip-card-id attribute.`);
+        } else if (cardIds.includes(cardId)) {
+            errors.push(`Duplicate flip card ID: "${cardId}". Each flip card must have a unique ID.`);
+        } else {
+            cardIds.push(cardId);
+        }
+    });
+
+    if (errors.length > 0) {
+        logger.fatal(`UIComponents.initFlipCards: Invalid structure:\n${errors.join('\n')}`, { domain: 'ui', operation: 'initFlipCards' });
+        return;
+    }
+
+    // Register flip cards with engagement manager
+    const currentSlideId = NavigationState.getCurrentSlideId();
+    if (currentSlideId) {
+        engagementManager.registerFlipCards(currentSlideId, cardIds);
+    }
+
+    // Initialize each flip card
+    flipCards.forEach(card => {
+        init(card);
+    });
+
+    return {
+        /**
+         * Programmatically flip a card by ID
+         * @param {string} cardId - The flip card ID
+         * @param {boolean} [flipped=true] - Whether to flip to back (true) or front (false)
+         */
+        flipCard(cardId, flipped = true) {
+            const card = container.querySelector(`[data-flip-card-id="${cardId}"]`);
+            if (card) {
+                if (flipped) {
+                    card.classList.add('is-flipped');
+                } else {
+                    card.classList.remove('is-flipped');
+                }
+                card.setAttribute('aria-expanded', String(flipped));
+                
+                // Track the flip for engagement
+                if (flipped) {
+                    const slideId = NavigationState.getCurrentSlideId();
+                    if (slideId) {
+                        engagementManager.trackFlipCardView(slideId, cardId);
+                    }
+                }
+            }
+        },
+
+        /**
+         * Get IDs of all flipped cards
+         * @returns {string[]} Array of flipped card IDs
+         */
+        getFlippedCards() {
+            return flipCards
+                .filter(card => card.classList.contains('is-flipped'))
+                .map(card => card.dataset.flipCardId);
+        },
+
+        /**
+         * Reset all cards to unflipped state
+         */
+        resetAll() {
+            flipCards.forEach(card => {
+                card.classList.remove('is-flipped');
+                card.setAttribute('aria-expanded', 'false');
+            });
+        },
+
+        /**
+         * Destroy event listeners
+         */
+        destroy() {
+            // Individual card cleanup is handled by init
+            // This is mainly for consistency with other component APIs
+        }
+    };
+}
+
+/**
+ * Initializes a single flip card component.
+ * Ensures the card has a tabindex for keyboard accessibility and handles click/keyboard events.
+ * Note: Flip card registration for engagement tracking is handled by ui-initializer
+ * after all flip cards on the slide are initialized.
+ * @param {HTMLElement} element - The flip card container element.
+ */
+export function init(element) {
+    if (!element) return;
+
+    const cardId = element.dataset.flipCardId;
+
+    // Ensure the card is keyboard focusable if not already set
+    if (!element.hasAttribute('tabindex')) {
+        element.setAttribute('tabindex', '0');
+    }
+
+    // Set initial ARIA attributes
+    if (!element.hasAttribute('aria-expanded')) {
+        element.setAttribute('aria-expanded', 'false');
+    }
+    if (!element.hasAttribute('role')) {
+        element.setAttribute('role', 'button');
+    }
+
+    // Toggle flip state
+    const toggleFlip = (e) => {
+        // Prevent default if it's a keydown event to avoid scrolling
+        if (e.type === 'keydown') {
+            e.preventDefault();
+        }
+        element.classList.toggle('is-flipped');
+        
+        const isFlipped = element.classList.contains('is-flipped');
+        element.setAttribute('aria-expanded', String(isFlipped));
+
+        // Track flip for engagement when card is flipped to back
+        if (isFlipped && cardId) {
+            const slideId = NavigationState.getCurrentSlideId();
+            if (slideId) {
+                engagementManager.trackFlipCardView(slideId, cardId);
+            }
+        }
+
+        // Announce state change for screen readers
+        const action = isFlipped ? 'Card flipped to reveal back' : 'Card flipped to show front';
+        announceToScreenReader(action);
+    };
+
+    // Click listener
+    element.addEventListener('click', toggleFlip);
+
+    // Keyboard listener (Enter or Space)
+    element.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            toggleFlip(e);
+        }
+    });
+}

package/framework/js/components/ui-components/form-validator.js

@@ -0,0 +1,76 @@
+/**
+ * @file form-validator.js
+ * @description Handles declarative form validation and submission feedback.
+ */
+
+export const schema = {
+    type: 'form-validator',
+    description: 'Declarative form validation with feedback',
+    example: `<form data-component="form-validator" data-success-message="Thanks for your feedback!" data-error-message="Please complete all fields." style="display: flex; flex-direction: column; gap: 12px; max-width: 320px;">
+  <label style="font-weight: 500; font-size: 0.875rem;">Name
+    <input type="text" required placeholder="Your name" style="display: block; width: 100%; margin-top: 4px; padding: 6px 10px; border: 1px solid #cbd5e1; border-radius: 4px;">
+  </label>
+  <label style="font-weight: 500; font-size: 0.875rem;">Email
+    <input type="email" required placeholder="you@example.com" style="display: block; width: 100%; margin-top: 4px; padding: 6px 10px; border: 1px solid #cbd5e1; border-radius: 4px;">
+  </label>
+  <button type="submit" class="btn btn-primary">Submit</button>
+</form>`,
+    properties: {
+        successMessage: { type: 'string', dataAttribute: 'data-success-message' },
+        errorMessage: { type: 'string', dataAttribute: 'data-error-message' },
+        closeModalOnSuccess: { type: 'boolean', dataAttribute: 'data-close-modal-on-success' }
+    },
+    structure: {
+        container: 'form[data-component="form-validator"]',
+        children: {}
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: 'components/forms.css',
+    engagementTracking: null,
+    emitsEvents: ['form:success', 'form:error']
+};
+
+import { showNotification } from './notifications.js';
+
+export function init(form) {
+    if (!form || form.tagName !== 'FORM') {
+        throw new Error('FormValidator: Element must be a <form> tag.');
+    }
+
+    const successMessage = form.dataset.successMessage || 'Form submitted successfully!';
+    const errorMessage = form.dataset.errorMessage || 'Please fill in all required fields.';
+
+    const handleSubmit = (event) => {
+        event.preventDefault();
+        
+        if (form.checkValidity()) {
+            showNotification(successMessage, 'success');
+            form.reset();
+            
+            // Dispatch success event for other components to listen to
+            form.dispatchEvent(new CustomEvent('form:success', { bubbles: true }));
+
+            // Check if we should close a parent modal
+            if (form.dataset.closeModalOnSuccess === 'true') {
+                const closeBtn = form.closest('.modal')?.querySelector('[data-action="close-modal"]');
+                if (closeBtn) closeBtn.click();
+            }
+        } else {
+            showNotification(errorMessage, 'error');
+            
+            // Dispatch error event
+            form.dispatchEvent(new CustomEvent('form:error', { bubbles: true }));
+        }
+    };
+
+    form.addEventListener('submit', handleSubmit);
+
+    return {
+        destroy: () => {
+            form.removeEventListener('submit', handleSubmit);
+        }
+    };
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Hero Layout Pattern
+ * 
+ * CSS-only component - no JavaScript behavior, just schema for discovery and validation.
+ * Full-width impactful intro slides with background support and overlays.
+ */
+
+export const schema = {
+    type: 'hero',
+    description: 'Full-width hero section with background image support',
+    example: `<div data-component="hero" class="hero-gradient">
+  <div class="hero-content">
+    <span class="hero-badge">New Course</span>
+    <h2 class="hero-title">Welcome to the Course</h2>
+    <p class="hero-subtitle">Learn everything you need to know.</p>
+    <div class="hero-cta"><button class="btn btn-primary">Get Started</button></div>
+  </div>
+</div>`,
+    properties: {
+        bgImage: {
+            type: 'string',
+            description: 'Background image URL (data-bg-image attribute)'
+        },
+        variant: {
+            type: 'string',
+            enum: ['default', 'overlay', 'overlay-light', 'dark', 'gradient', 'split'],
+            default: 'default',
+            description: 'Visual style variant (add as class, e.g., hero-overlay)'
+        }
+    },
+    structure: {
+        container: '[data-component="hero"]',
+        children: {
+            content: { selector: '.hero-content' },
+            title: { selector: '.hero-title, h1' },
+            subtitle: { selector: '.hero-subtitle' },
+            cta: { selector: '.hero-cta' }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssOnly: true,
+    cssFile: 'components/hero.css'
+};
+
+/** No-op initializer — CSS-only component, registered for consistency. */
+export function init() {}

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

@@ -0,0 +1,12 @@
+// index.js — UI Components shared utilities
+
+import accessibilityManager from '../../managers/accessibility-manager.js';
+
+/**
+ * Announces a message to a screen reader.
+ * @param {string} message - The message to announce.
+ * @param {string} [priority='polite'] - The assertiveness level ('polite' or 'assertive').
+ */
+export function announceToScreenReader(message, priority = 'polite') {
+  accessibilityManager.announce(message, priority);
+}