coursecode 0.1.0

package/framework/js/components/ui-components/conditional-display.js

@@ -0,0 +1,150 @@
+/**
+ * @file conditional-display.js
+ * @description Declarative component for conditionally showing/hiding content based on engagement, flags, and interactions.
+ *
+ * Usage examples:
+ *
+ * Simple engagement condition:
+ *   <div data-component="conditional" data-condition="engagement.viewAllTabs">
+ *     Content shown after all tabs viewed
+ *   </div>
+ *
+ * Flag condition:
+ *   <div data-component="conditional" data-condition="flag.intro-complete">
+ *     Content shown when flag is set
+ *   </div>
+ *
+ * Multiple conditions (AND):
+ *   <div data-component="conditional"
+ *        data-conditions="engagement.viewAllTabs,flag.step1-done"
+ *        data-mode="all">
+ *     Content shown when both conditions met
+ *   </div>
+ *
+ * Inverse (hide when condition met):
+ *   <div data-component="conditional"
+ *        data-condition="engagement.viewAllTabs"
+ *        data-show-when="false">
+ *     "Please view all tabs above" message (hidden when tabs viewed)
+ *   </div>
+ *
+ * Custom display mode:
+ *   <div data-component="conditional"
+ *        data-condition="flag.menu-open"
+ *        data-display="flex">
+ *     Flexbox container shown when flag set
+ *   </div>
+ */
+
+export const schema = {
+    type: 'conditional',
+    description: 'Conditionally show/hide content based on engagement or flags',
+    example: `<div style="display: flex; flex-direction: column; gap: 12px;">
+  <div data-component="conditional" data-condition="engagement.viewAllTabs" style="padding: 12px; border: 1px dashed #94a3b8; border-radius: 6px; color: #64748b;">
+    <p style="margin: 0; font-size: 0.875rem;">🔀 <strong>Conditional block</strong> — this content appears when <code>engagement.viewAllTabs</code> is met.</p>
+  </div>
+  <div data-component="conditional" data-condition="flag.intro-complete" data-show-when="false" style="padding: 12px; border: 1px dashed #f59e0b; border-radius: 6px; color: #92400e;">
+    <p style="margin: 0; font-size: 0.875rem;">🙈 <strong>Inverse block</strong> — this content <em>hides</em> when <code>flag.intro-complete</code> is set.</p>
+  </div>
+</div>`,
+    properties: {
+        condition: { type: 'string', dataAttribute: 'data-condition' },
+        conditions: { type: 'string', dataAttribute: 'data-conditions' },
+        mode: { type: 'string', enum: ['all', 'any'], default: 'all', dataAttribute: 'data-mode' },
+        showWhen: { type: 'boolean', default: true, dataAttribute: 'data-show-when' },
+        display: { type: 'string', default: 'block', dataAttribute: 'data-display' }
+    },
+    structure: {
+        container: '[data-component="conditional"]',
+        children: {}
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: null,
+    engagementTracking: null,
+    emitsEvents: []
+};
+
+import { conditionalDisplay } from '../../utilities/conditional-display.js';
+import { logger } from '../../utilities/logger.js';
+
+/**
+ * Initializes conditional display for an element.
+ *
+ * @param {HTMLElement|string} root - The element or selector
+ * @param {object} options - Configuration options (optional, can use data attributes)
+ * @returns {object} API with cleanup method
+ */
+export function init(root, options = {}) {
+    const element = resolveRoot(root);
+    if (!element) {
+        logger.fatal('ConditionalDisplay: element not found', { domain: 'ui', operation: 'initConditionalDisplay' });
+        return;
+    }
+
+    // Check if already initialized (prevent double initialization)
+    if (element.dataset.conditionalInitialized === 'true') {
+        throw new Error('[ConditionalDisplay] Element already initialized. Each element should only be initialized once.');
+    }
+
+    // Mark as initialized
+    element.dataset.conditionalInitialized = 'true';
+
+    // Read config from data attributes if no options are passed (declarative mode)
+    const condition = options.condition || element.dataset.condition;
+    const conditionsAttr = options.conditions || element.dataset.conditions;
+    const mode = options.mode || element.dataset.mode || 'all';
+    const showWhen = options.showWhen !== undefined
+        ? options.showWhen
+        : (element.dataset.showWhen !== 'false'); // Default true unless explicitly "false"
+    const transition = options.transition !== undefined
+        ? options.transition
+        : (element.dataset.transition !== 'false'); // Default true
+    const display = options.display || element.dataset.display || 'block';
+
+    // Parse conditions
+    let conditions;
+    if (conditionsAttr) {
+        // Multiple conditions from comma-separated string
+        conditions = conditionsAttr.split(',').map(c => c.trim());
+    } else if (condition) {
+        // Single condition
+        conditions = condition;
+    } else {
+        logger.fatal('ConditionalDisplay: No condition specified. Use data-condition or data-conditions attribute.', { domain: 'ui', operation: 'initConditionalDisplay' });
+        return;
+    }
+
+    // Set up conditional display tracking
+    const cleanup = conditionalDisplay.showWhen(element, conditions, {
+        mode,
+        showWhen,
+        transition,
+        display,
+        initialCheck: true
+    });
+
+    // Return API with cleanup that also removes initialized flag
+    return {
+        destroy: () => {
+            cleanup();
+            delete element.dataset.conditionalInitialized;
+        },
+        element
+    };
+}
+
+/**
+ * Resolves a root element reference to an actual DOM element.
+ *
+ * @param {HTMLElement|string} ref - Element or selector string
+ * @returns {HTMLElement|null} Resolved element or null
+ */
+function resolveRoot(ref) {
+    if (!ref) return null;
+    if (ref instanceof Element) return ref;
+    if (typeof ref === 'string') return document.querySelector(ref);
+    return null;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Content Image Layout Pattern
+ * 
+ * CSS-only component for text with diagram/screenshot side by side.
+ */
+
+export const schema = {
+    type: 'content-image',
+    description: 'Two-column layout with text and image',
+    example: `<div data-component="content-image">
+  <div>
+    <h3>Visual Learning</h3>
+    <p>Pair text with images for a clear, engaging layout. The image column adapts to the content automatically.</p>
+  </div>
+  <div>
+    <img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='320' height='200' fill='%23e2e8f0'%3E%3Crect width='320' height='200' rx='8'/%3E%3Ctext x='50%25' y='50%25' dominant-baseline='middle' text-anchor='middle' fill='%2394a3b8' font-family='system-ui' font-size='14'%3EImage Placeholder%3C/text%3E%3C/svg%3E" alt="Placeholder">
+  </div>
+</div>`,
+    properties: {
+        reverse: {
+            type: 'boolean',
+            default: false,
+            description: 'Reverse column order (add .reverse class)'
+        }
+    },
+    structure: {
+        container: '[data-component="content-image"]',
+        children: {
+            image: { selector: 'img', required: true }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssOnly: true,
+    cssFile: 'components/content-image.css'
+};
+
+/** No-op initializer — CSS-only component, registered for consistency. */
+export function init() {}

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

@@ -0,0 +1,262 @@
+/**
+ * @file dropdown.js
+ * @description Custom dropdown management with event delegation.
+ * 
+ * Usage example:
+ *   <div id="role-dropdown">
+ *     <button class="dropdown-trigger" data-action="toggle-dropdown">Choose role</button>
+ *     <div class="dropdown-menu">
+ *       <button class="dropdown-item" data-action="select-item">Engineer</button>
+ *     </div>
+ *   </div>
+ *   UIComponents.initDropdown('role-dropdown', { onChange: (value) => console.log(value) });
+ */
+
+export const schema = {
+    type: 'dropdown',
+    description: 'Custom dropdown select with keyboard navigation',
+    example: `<div data-component="dropdown" class="dropdown">
+  <button class="dropdown-trigger" aria-haspopup="true" aria-expanded="false">Select an option</button>
+  <ul class="dropdown-menu" role="menu">
+    <li class="dropdown-item" role="menuitem" tabindex="-1">Introduction</li>
+    <li class="dropdown-item" role="menuitem" tabindex="-1">Components</li>
+    <li class="dropdown-item" role="menuitem" tabindex="-1">Interactions</li>
+  </ul>
+</div>`,
+    properties: {
+        onChange: { type: 'function', description: 'Callback when selection changes' }
+    },
+    structure: {
+        container: '[data-component="dropdown"]',
+        children: {
+            trigger: { selector: '.dropdown-trigger', required: true },
+            menu: { selector: '.dropdown-menu', required: true },
+            item: { selector: '.dropdown-item', required: true, minItems: 1 }
+        }
+    }
+};
+
+export const metadata = {
+    category: 'ui-component',
+    cssFile: 'components/dropdown.css',
+    engagementTracking: null,
+    emitsEvents: ['dropdown:change']
+};
+
+import { validateDropdownActions } from '../../validation/html-validators.js';
+import { logger } from '../../utilities/logger.js';
+
+const dropdowns = new Map();
+
+// Global click handler for closing dropdowns (attached once when first dropdown is initialized)
+let globalHandlerAttached = false;
+
+function ensureGlobalHandler() {
+    if (globalHandlerAttached) return;
+
+    document.addEventListener('click', (event) => {
+        // If the click is on a dropdown trigger, let the component handle it
+        if (event.target.closest('.dropdown-trigger')) {
+            return;
+        }
+
+        // Close any dropdown that is open and was not the target of the click
+        for (const [id, dropdown] of dropdowns.entries()) {
+            if (dropdown.menu.classList.contains('active') && !dropdown.element.contains(event.target)) {
+                closeDropdown(id);
+            }
+        }
+    });
+
+    globalHandlerAttached = true;
+}
+
+function resolveRoot(ref) {
+    if (!ref) return null;
+    if (ref instanceof Element) return ref;
+    if (typeof ref === 'string') return document.querySelector(ref);
+    return null;
+}
+
+export function init(root, options = {}) {
+    ensureGlobalHandler();
+
+    const dropdown = resolveRoot(root);
+    if (!dropdown) {
+        logger.fatal(`Dropdown with selector "${root}" not found`, { domain: 'ui', operation: 'initDropdown' });
+        return;
+    }
+
+    const dropdownId = dropdown.id;
+    if (!dropdownId) {
+        logger.fatal('Dropdown container element must have an ID.', { domain: 'ui', operation: 'initDropdown' });
+        return;
+    }
+
+    const trigger = dropdown.querySelector('.dropdown-trigger');
+    const menu = dropdown.querySelector('.dropdown-menu');
+    const items = dropdown.querySelectorAll('.dropdown-item');
+
+    if (!trigger || !menu) {
+        logger.fatal(`Dropdown "${dropdownId}" missing required elements (.dropdown-trigger or .dropdown-menu)`, { domain: 'ui', operation: 'initDropdown' });
+        return;
+    }
+
+    // Validate that dropdown has required data-action attributes
+    const validation = validateDropdownActions(dropdown);
+    if (!validation.valid) {
+        const errorMessages = validation.errors.map(e => `${e.message}: ${e.context.fix}`).join('; ');
+        logger.fatal(`Dropdown "${dropdownId}" validation failed: ${errorMessages}`, { domain: 'ui', operation: 'initDropdown' });
+        return;
+    }
+
+    const config = {
+        onChange: options.onChange || null,
+        ...options
+    };
+
+    dropdowns.set(dropdownId, { element: dropdown, trigger, menu, items, config });
+
+    // Setup ARIA attributes
+    trigger.setAttribute('aria-haspopup', 'listbox');
+    trigger.setAttribute('aria-expanded', 'false');
+
+    items.forEach((item) => {
+        item.setAttribute('role', 'option');
+        item.setAttribute('tabindex', '0');
+    });
+
+    // Delegated event listener for the entire dropdown
+    dropdown.addEventListener('click', (event) => {
+        const actionTarget = event.target.closest('[data-action]');
+        if (!actionTarget) return;
+
+        const action = actionTarget.dataset.action;
+
+        if (action === 'toggle-dropdown') {
+            // Close other open dropdowns first
+            for (const [id] of dropdowns.entries()) {
+                if (id !== dropdownId) closeDropdown(id);
+            }
+            toggleDropdown(dropdownId);
+        } else if (action === 'select-item') {
+            const itemIndex = Array.from(items).indexOf(actionTarget);
+            if (itemIndex > -1) {
+                selectDropdownItem(dropdownId, itemIndex);
+            }
+        }
+    });
+
+    // Keyboard navigation for the menu
+    menu.addEventListener('keydown', (event) => handleDropdownKeyboard(dropdownId, event));
+
+    return {
+        destroy: () => {
+            dropdowns.delete(dropdownId);
+        }
+    };
+}
+
+export function toggleDropdown(dropdownId) {
+  const entry = dropdowns.get(dropdownId);
+  if (!entry) return;
+
+  const isOpen = entry.menu.classList.contains('active');
+  if (isOpen) {
+    closeDropdown(dropdownId);
+  } else {
+    openDropdown(dropdownId);
+  }
+}
+
+export function openDropdown(dropdownId) {
+  const entry = dropdowns.get(dropdownId);
+  if (!entry) return;
+
+  // Close any other open dropdowns
+  for (const [id] of dropdowns.entries()) {
+    if (id !== dropdownId) {
+      closeDropdown(id);
+    }
+  }
+
+  entry.menu.classList.add('active');
+  entry.trigger.classList.add('active');
+  entry.trigger.setAttribute('aria-expanded', 'true');
+}
+
+export function closeDropdown(dropdownId) {
+  const entry = dropdowns.get(dropdownId);
+  if (!entry) return;
+
+  entry.menu.classList.remove('active');
+  entry.trigger.classList.remove('active');
+  entry.trigger.setAttribute('aria-expanded', 'false');
+}
+
+function selectDropdownItem(dropdownId, index) {
+  const entry = dropdowns.get(dropdownId);
+  if (!entry) return;
+
+  const { items, trigger, config } = entry;
+  const selected = items[index];
+
+  items.forEach(item => item.classList.remove('selected'));
+  selected.classList.add('selected');
+
+  const triggerText = trigger.querySelector('.dropdown-text') || trigger;
+  triggerText.textContent = selected.textContent;
+
+  closeDropdown(dropdownId);
+  trigger.focus(); // Return focus to the trigger
+
+  if (config.onChange) {
+    config.onChange(selected.dataset.value || selected.textContent, index);
+  }
+
+  // Dispatch a custom event for declarative usage
+  const event = new CustomEvent('dropdown:change', {
+    bubbles: true,
+    detail: {
+      value: selected.dataset.value || selected.textContent,
+      index: index,
+      text: selected.textContent
+    }
+  });
+  entry.element.dispatchEvent(event);
+}
+
+function handleDropdownKeyboard(dropdownId, event) {
+  const entry = dropdowns.get(dropdownId);
+  if (!entry) return;
+
+  const { items, trigger } = entry;
+  const currentIndex = Array.from(items).indexOf(document.activeElement);
+
+  switch (event.key) {
+    case 'ArrowDown':
+      event.preventDefault();
+      if (currentIndex < items.length - 1) {
+        items[currentIndex + 1].focus();
+      }
+      break;
+    case 'ArrowUp':
+      event.preventDefault();
+      if (currentIndex > 0) {
+        items[currentIndex - 1].focus();
+      }
+      break;
+    case 'Escape':
+      event.preventDefault();
+      closeDropdown(dropdownId);
+      trigger.focus();
+      break;
+    case 'Enter':
+    case ' ':
+      event.preventDefault();
+      if (currentIndex > -1) {
+        selectDropdownItem(dropdownId, currentIndex);
+      }
+      break;
+  }
+}