coursecode 0.1.0

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

@@ -0,0 +1,121 @@
+/**
+ * @file callout.js
+ * @description Optional icon hydration for callout.
+ *
+ * Usage:
+ * <aside class="callout callout--warning" data-component="callout" data-icon="auto">
+ *   <h4 class="callout__title">Title</h4>
+ *   <div class="callout__body"><p>Body text.</p></div>
+ * </aside>
+ */
+
+import { iconManager } from '../../utilities/icons.js';
+
+export const schema = {
+    type: 'callout',
+    description: 'Modern callout with optional automatic icon injection',
+    example: `<aside class="callout callout--info" data-component="callout" data-icon="auto">
+  <h4 class="callout__title">Helpful context</h4>
+  <div class="callout__body"><p>Message text.</p></div>
+</aside>`,
+    properties: {
+        icon: {
+            type: 'string',
+            required: false,
+            description: 'Icon name or "auto" (maps from severity).'
+        },
+        iconSize: {
+            type: 'string',
+            required: false,
+            description: 'Icon size token: xs|sm|md|lg|xl|2xl|3xl (default: sm).'
+        },
+        iconClass: {
+            type: 'string',
+            required: false,
+            description: 'Optional extra icon class.'
+        }
+    },
+    structure: {
+        container: '[data-component="callout"]',
+        children: {
+            title: { selector: '.callout__title', required: true },
+            body: { selector: '.callout__body', required: true },
+            icon: { selector: '.callout__icon', required: false }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: 'components/callouts.css',
+    engagementTracking: null,
+    emitsEvents: []
+};
+
+const ICON_BY_SEVERITY = Object.freeze({
+    neutral: 'info',
+    info: 'info',
+    success: 'check-circle',
+    warning: 'alert-circle',
+    danger: 'alert-octagon'
+});
+
+function getSeverity(element) {
+    if (element.classList.contains('callout--danger')) return 'danger';
+    if (element.classList.contains('callout--warning')) return 'warning';
+    if (element.classList.contains('callout--success')) return 'success';
+    if (element.classList.contains('callout--neutral')) return 'neutral';
+    return 'info';
+}
+
+function resolveIconName(element, requested) {
+    if (requested && requested !== 'auto') return requested;
+    const severity = getSeverity(element);
+    return ICON_BY_SEVERITY[severity] || 'info';
+}
+
+function findTopLevelIconSlot(element) {
+    return Array.from(element.children).find((child) => child.classList?.contains('callout__icon')) || null;
+}
+
+function ensureIconSlot(element) {
+    const existing = findTopLevelIconSlot(element);
+    if (existing) {
+        existing.setAttribute('aria-hidden', 'true');
+        return existing;
+    }
+
+    const iconSlot = document.createElement('span');
+    iconSlot.className = 'callout__icon';
+    iconSlot.setAttribute('aria-hidden', 'true');
+
+    const title = Array.from(element.children).find((child) => child.classList?.contains('callout__title'));
+    if (title) {
+        element.insertBefore(iconSlot, title);
+    } else {
+        element.prepend(iconSlot);
+    }
+
+    return iconSlot;
+}
+
+export function init(element) {
+    if (!element?.classList?.contains('callout')) return;
+
+    const requested = (element.dataset.icon || '').trim();
+    const existingIconSlot = findTopLevelIconSlot(element);
+
+    // Preserve manual icon markup unless explicit icon hydration is requested.
+    if (!requested && existingIconSlot) return;
+
+    // Keep no-icon callouts clean unless icon hydration is requested.
+    if (!requested && !existingIconSlot) return;
+
+    const iconName = resolveIconName(element, requested);
+    const iconSize = (element.dataset.iconSize || 'sm').trim();
+    const iconClass = (element.dataset.iconClass || '').trim();
+    const iconSlot = ensureIconSlot(element);
+
+    iconSlot.innerHTML = iconManager.getIcon(iconName, { size: iconSize, class: iconClass });
+}
+

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

@@ -0,0 +1,145 @@
+/**
+ * @file carousel.js
+ * @description A simple, accessible image carousel/slider component.
+ *
+ * Usage (Declarative):
+ * <div class="carousel" data-component="carousel" id="my-carousel">
+ *   <div class="carousel-track">
+ *     <div class="carousel-slide">...</div>
+ *     <div class="carousel-slide">...</div>
+ *   </div>
+ *   <button class="carousel-button prev" data-action="prev-slide" aria-label="Previous Slide">&#10094;</button>
+ *   <button class="carousel-button next" data-action="next-slide" aria-label="Next Slide">&#10095;</button>
+ *   <div class="carousel-dots"></div>
+ * </div>
+ */
+
+// Schema for validation, linting, and AI-assisted authoring
+export const schema = {
+    type: 'carousel',
+    description: 'Accessible image carousel/slider with dot navigation',
+    example: `<div data-component="carousel">
+  <div class="carousel-track">
+    <div class="carousel-slide active"><div class="card no-hover"><div class="card-body"><h3>Slide 1</h3><p>First slide content with important information.</p></div></div></div>
+    <div class="carousel-slide"><div class="card no-hover"><div class="card-body"><h3>Slide 2</h3><p>Second slide with additional details.</p></div></div></div>
+    <div class="carousel-slide"><div class="card no-hover"><div class="card-body"><h3>Slide 3</h3><p>Third slide wrapping up the sequence.</p></div></div></div>
+  </div>
+  <button class="carousel-button prev" data-action="prev-slide" aria-label="Previous Slide">&#10094;</button>
+  <button class="carousel-button next" data-action="next-slide" aria-label="Next Slide">&#10095;</button>
+  <div class="carousel-dots"></div>
+</div>`,
+    properties: {
+        autoPlay: { type: 'boolean', default: false, description: 'Auto-advance slides' },
+        interval: { type: 'number', default: 5000, description: 'Auto-advance interval in ms' }
+    },
+    structure: {
+        container: '[data-component="carousel"]',
+        children: {
+            track: { selector: '.carousel-track', required: true },
+            slide: { selector: '.carousel-slide', parent: '.carousel-track', required: true, minItems: 1 },
+            prevButton: { selector: '[data-action="prev-slide"]' },
+            nextButton: { selector: '[data-action="next-slide"]' },
+            dots: { selector: '.carousel-dots' }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: 'components/carousel.css',
+    engagementTracking: null,
+    emitsEvents: ['carousel:slide-changed']
+};
+
+import { logger } from '../../utilities/logger.js';
+
+/**
+ * Initializes a carousel component.
+ * @param {HTMLElement} container - The main container for the carousel.
+ */
+export function init(container) {
+    if (!container) {
+        logger.fatal('initCarousel: container not found.', { domain: 'ui', operation: 'initCarousel' });
+        return;
+    }
+
+    const track = container.querySelector('.carousel-track');
+    const slides = Array.from(container.querySelectorAll('.carousel-slide'));
+    const prevButton = container.querySelector('[data-action="prev-slide"]');
+    const nextButton = container.querySelector('[data-action="next-slide"]');
+    const dotsContainer = container.querySelector('.carousel-dots');
+
+    if (!track || !slides.length) {
+        logger.fatal('initCarousel: A track and slides are required. Ensure carousel HTML structure is correct with .carousel-track and .carousel-slide elements.', { domain: 'ui', operation: 'initCarousel' });
+        return;
+    }
+
+    let currentIndex = 0;
+
+    const updateCarousel = () => {
+        // Move the track
+        track.style.transform = `translateX(-${currentIndex * 100}%)`;
+
+        // Update buttons
+        if (prevButton) {
+            prevButton.disabled = currentIndex === 0;
+        }
+        if (nextButton) {
+            nextButton.disabled = currentIndex === slides.length - 1;
+        }
+
+        // Update dots
+        if (dotsContainer) {
+            const dots = Array.from(dotsContainer.children);
+            dots.forEach((dot, index) => {
+                dot.classList.toggle('active', index === currentIndex);
+            });
+        }
+        
+        // Update slide visibility for screen readers
+        slides.forEach((slide, index) => {
+            slide.setAttribute('aria-hidden', index !== currentIndex);
+        });
+    };
+
+    const goToSlide = (index) => {
+        if (index < 0 || index >= slides.length) return;
+        currentIndex = index;
+        updateCarousel();
+    };
+
+    // Create dot indicators
+    if (dotsContainer) {
+        dotsContainer.innerHTML = '';
+        slides.forEach((_, index) => {
+            const dot = document.createElement('button');
+            dot.className = 'carousel-dot';
+            dot.setAttribute('aria-label', `Go to slide ${index + 1}`);
+            dot.addEventListener('click', () => goToSlide(index));
+            dotsContainer.appendChild(dot);
+        });
+    }
+
+    const clickHandler = (event) => {
+        const actionTarget = event.target.closest('[data-action]');
+        if (!actionTarget) return;
+
+        const action = actionTarget.dataset.action;
+        if (action === 'next-slide') {
+            goToSlide(currentIndex + 1);
+        } else if (action === 'prev-slide') {
+            goToSlide(currentIndex - 1);
+        }
+    };
+
+    container.addEventListener('click', clickHandler);
+
+    // Initialize state
+    updateCarousel();
+
+    return {
+        destroy: () => {
+            container.removeEventListener('click', clickHandler);
+        }
+    };
+}

package/framework/js/components/ui-components/checkbox-group.js

@@ -0,0 +1,87 @@
+/**
+ * @file checkbox-group.js
+ * @description Handles a group of checkboxes, aggregating their values and emitting change events.
+ */
+
+export const schema = {
+    type: 'checkbox-group',
+    description: 'Group of checkboxes with aggregated value tracking',
+    example: `<div data-component="checkbox-group" class="checkbox-group">
+  <div class="checkbox-option"><input type="checkbox" value="html" id="cb-html" checked><label for="cb-html" class="checkbox-label">HTML &amp; CSS</label></div>
+  <div class="checkbox-option"><input type="checkbox" value="js" id="cb-js"><label for="cb-js" class="checkbox-label">JavaScript</label></div>
+  <div class="checkbox-option"><input type="checkbox" value="a11y" id="cb-a11y"><label for="cb-a11y" class="checkbox-label">Accessibility</label></div>
+</div>`,
+    properties: {},
+    structure: {
+        container: '[data-component="checkbox-group"]',
+        children: {
+            checkbox: { selector: 'input[type="checkbox"]', required: true, minItems: 1 }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: 'components/checkbox-group.css',
+    engagementTracking: null,
+    emitsEvents: ['checkbox-group:change']
+};
+
+import { logger } from '../../utilities/logger.js';
+
+export function init(element) {
+    if (!element) {
+        logger.fatal('CheckboxGroup: Container element is required', { domain: 'ui', operation: 'initCheckboxGroup' });
+        return;
+    }
+
+    const checkboxes = element.querySelectorAll('input[type="checkbox"]');
+
+    if (checkboxes.length === 0) {
+        logger.fatal('CheckboxGroup: No checkbox inputs found in container', { domain: 'ui', operation: 'initCheckboxGroup' });
+        return;
+    }
+
+    const handleChange = () => {
+        const checked = Array.from(checkboxes).filter(cb => cb.checked);
+        const values = checked.map(cb => cb.value);
+        
+        // Try to find labels. 
+        // 1. Look for .checkbox-label inside the closest .checkbox-option (Framework convention)
+        // 2. Look for associated <label> (Standard HTML)
+        // 3. Use value
+        const labels = checked.map(cb => {
+            const option = cb.closest('.checkbox-option');
+            if (option) {
+                const labelEl = option.querySelector('.checkbox-label');
+                if (labelEl) return labelEl.textContent;
+            }
+            if (cb.labels && cb.labels.length > 0) return cb.labels[0].textContent;
+            return cb.value;
+        });
+
+        const event = new CustomEvent('checkbox-group:change', {
+            bubbles: true,
+            detail: {
+                values: values,
+                labels: labels,
+                count: checked.length,
+                // Helper for simple display
+                value: labels.join(', ') 
+            }
+        });
+        element.dispatchEvent(event);
+    };
+
+    checkboxes.forEach(cb => {
+        cb.addEventListener('change', handleChange);
+    });
+
+    return {
+        destroy: () => {
+            checkboxes.forEach(cb => {
+                cb.removeEventListener('change', handleChange);
+            });
+        }
+    };
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Checklist Layout Pattern
+ * 
+ * CSS-only component for task/requirement checklists.
+ */
+
+export const schema = {
+    type: 'checklist',
+    description: 'Checklist with items and completion states',
+    example: `<div data-component="checklist">
+  <div class="checklist-item completed"><span class="checklist-text">Review course outline</span></div>
+  <div class="checklist-item completed"><span class="checklist-text">Create slide content</span></div>
+  <div class="checklist-item"><span class="checklist-text">Add interactions and assessments</span></div>
+</div>`,
+    properties: {
+        style: {
+            type: 'string',
+            enum: ['default', 'cards', 'minimal', 'numbered'],
+            default: 'default',
+            description: 'Visual style variant (data-checklist-style attribute)'
+        }
+    },
+    structure: {
+        container: '[data-component="checklist"]',
+        children: {
+            item: { selector: '.checklist-item', required: true, minItems: 1 },
+            text: { selector: '.checklist-text', parent: '.checklist-item', required: true },
+            status: { selector: '.checklist-status', parent: '.checklist-item' }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssOnly: true,
+    cssFile: 'components/checklist.css'
+};
+
+/** No-op initializer — CSS-only component, registered for consistency. */
+export function init() {}

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

@@ -0,0 +1,114 @@
+/**
+ * @file collapse.js
+ * @description Handles "Show More/Less" or collapsible content sections.
+ *
+ * Usage (Declarative):
+ * <div data-component="collapse">
+ *   <div class="collapse-panel" id="transcript-panel">
+ *     <p>Long content goes here...</p>
+ *   </div>
+ *   <button class="collapse-trigger" data-action="toggle-collapse" aria-controls="transcript-panel" aria-expanded="false">
+ *     <span class="collapse-text-show">Show Transcript</span>
+ *     <span class="collapse-text-hide">Hide Transcript</span>
+ *   </button>
+ * </div>
+ */
+
+export const schema = {
+    type: 'collapse',
+    description: 'Collapsible content section with show/hide toggle',
+    example: `<div data-component="collapse">
+  <button class="btn btn-secondary collapse-trigger" data-action="toggle-collapse" aria-controls="preview-collapse" aria-expanded="false">
+    <span class="collapse-text-show">Show Details</span><span class="collapse-text-hide">Hide Details</span>
+  </button>
+  <div class="collapse-panel mt-3" id="preview-collapse">
+    <div class="p-4 bg-gray-100 rounded"><p>This content is hidden by default. Click the button above to toggle visibility.</p></div>
+  </div>
+</div>`,
+    properties: {},
+    structure: {
+        container: '[data-component="collapse"]',
+        children: {
+            panel: { selector: '.collapse-panel', required: true },
+            trigger: { selector: '[data-action="toggle-collapse"]', required: true }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: 'components/collapse.css',
+    engagementTracking: null,
+    emitsEvents: ['collapse:toggle']
+};
+
+import { logger } from '../../utilities/logger.js';
+
+/**
+ * Initializes a collapse component.
+ * @param {HTMLElement} container - The main container for the collapse component.
+ * @returns {object} An object with a `destroy` method.
+ */
+export function init(container) {
+    if (!container) {
+        logger.fatal('initCollapse: container not found.', { domain: 'ui', operation: 'initCollapse' });
+        return;
+    }
+
+    const trigger = container.querySelector('[data-action="toggle-collapse"]');
+    if (!trigger) {
+        logger.fatal('initCollapse: No trigger found with data-action="toggle-collapse". Ensure collapse trigger button exists.', { domain: 'ui', operation: 'initCollapse' });
+        return;
+    }
+
+    const panelId = trigger.getAttribute('aria-controls');
+    const panel = panelId ? container.querySelector(`#${panelId}`) : null;
+
+    if (!panel) {
+        logger.fatal(`initCollapse: No panel found with ID "${panelId}". Ensure trigger's aria-controls matches panel ID.`, { domain: 'ui', operation: 'initCollapse' });
+        return;
+    }
+
+    const isExpanded = trigger.getAttribute('aria-expanded') === 'true';
+    panel.style.maxHeight = isExpanded ? `${panel.scrollHeight}px` : '0';
+    container.classList.toggle('expanded', isExpanded);
+
+    const toggle = () => {
+        const currentlyExpanded = trigger.getAttribute('aria-expanded') === 'true';
+        
+        trigger.setAttribute('aria-expanded', !currentlyExpanded);
+        container.classList.toggle('expanded', !currentlyExpanded);
+
+        if (!currentlyExpanded) {
+            // Expanding
+            panel.style.display = 'block'; // Make it visible before calculating scrollHeight
+            panel.style.maxHeight = `${panel.scrollHeight}px`;
+        } else {
+            // Collapsing
+            panel.style.maxHeight = '0';
+        }
+    };
+
+    // Handle transition end to set display: none for accessibility and performance
+    panel.addEventListener('transitionend', () => {
+        if (trigger.getAttribute('aria-expanded') === 'false') {
+            panel.style.display = 'none';
+        }
+    });
+    
+    // Ensure panel is correctly displayed or hidden on init
+    if (trigger.getAttribute('aria-expanded') === 'false') {
+        panel.style.display = 'none';
+    } else {
+        panel.style.display = 'block';
+    }
+
+
+    trigger.addEventListener('click', toggle);
+
+    return {
+        destroy: () => {
+            trigger.removeEventListener('click', toggle);
+        }
+    };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Comparison Layout Pattern
+ * 
+ * CSS-only component for side-by-side comparison of two options.
+ */
+
+export const schema = {
+    type: 'comparison',
+    description: 'Side-by-side comparison grid',
+    example: `<div data-component="comparison">
+  <div class="comparison-item"><h3>Advantages</h3><ul><li>Easy to use</li><li>Fast performance</li><li>Great documentation</li></ul></div>
+  <div class="comparison-item"><h3>Limitations</h3><ul><li>Steeper learning curve</li><li>Limited integrations</li><li>Requires modern browser</li></ul></div>
+</div>`,
+    properties: {},
+    structure: {
+        container: '[data-component="comparison"]',
+        children: {
+            item: { selector: '.comparison-item', required: true, minItems: 2 }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssOnly: true,
+    cssFile: 'components/comparison.css'
+};
+
+/** No-op initializer — CSS-only component, registered for consistency. */
+export function init() {}