@africode/core 5.0.0

package/core/hmr-client.js

@@ -0,0 +1,204 @@
+/**
+ * AfriCode HMR Client
+ * 
+ * Injected into pages during development
+ * Handles module reloading and page updates
+ */
+
+(function hmrClient() {
+    const WS_URL = `ws://${window.location.hostname}:${window.location.port === '3000' ? '3000' : window.location.port}`;
+    let ws = null;
+    let reconnectAttempts = 0;
+    const MAX_RECONNECT = 10;
+    const RECONNECT_DELAY = 1000;
+
+    /**
+     * Connect to HMR server via WebSocket
+     */
+    function connect() {
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            return;
+        }
+
+        try {
+            ws = new WebSocket(WS_URL);
+
+            ws.onopen = () => {
+                console.log(`%c[HMR] Connected`, 'color: green; font-weight: bold;');
+                reconnectAttempts = 0;
+                sendPing();
+            };
+
+            ws.onmessage = (event) => {
+                try {
+                    const message = JSON.parse(event.data);
+                    handleUpdate(message);
+                } catch (err) {
+                    console.error('[HMR] Failed to parse message:', err);
+                }
+            };
+
+            ws.onerror = (error) => {
+                console.error('[HMR] WebSocket error:', error);
+            };
+
+            ws.onclose = () => {
+                console.log(`%c[HMR] Disconnected`, 'color: orange; font-weight: bold;');
+                scheduleReconnect();
+            };
+        } catch (err) {
+            console.error('[HMR] Connection failed:', err);
+            scheduleReconnect();
+        }
+    }
+
+    /**
+     * Schedule reconnection with exponential backoff
+     */
+    function scheduleReconnect() {
+        if (reconnectAttempts >= MAX_RECONNECT) {
+            console.warn('[HMR] Max reconnection attempts reached. Giving up.');
+            return;
+        }
+
+        reconnectAttempts++;
+        const delay = RECONNECT_DELAY * Math.pow(1.5, reconnectAttempts - 1);
+        console.log(`[HMR] Reconnecting in ${delay.toFixed(0)}ms... (attempt ${reconnectAttempts})`);
+
+        setTimeout(connect, delay);
+    }
+
+    /**
+     * Send ping to keep connection alive
+     */
+    function sendPing() {
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({ type: 'ping' }));
+            setTimeout(sendPing, 30000); // Ping every 30 seconds
+        }
+    }
+
+    /**
+     * Handle update from HMR server
+     */
+    function handleUpdate(message) {
+        if (message.type !== 'update') {
+            return;
+        }
+
+        const { moduleType, modulePath, filename, timestamp } = message;
+
+        console.log(`%c[HMR] Update received: ${filename}`, 'color: #4CAF50; font-weight: bold;');
+
+        // Handle different module types
+        switch (moduleType) {
+            case 'page':
+                reloadPage();
+                break;
+
+            case 'style':
+                reloadStyles();
+                break;
+
+            case 'component':
+                reloadComponent(modulePath);
+                break;
+
+            case 'core':
+                // Core module changes require full reload
+                reloadPage();
+                break;
+
+            case 'markup':
+                reloadPage();
+                break;
+
+            default:
+                // Unknown type, do full reload to be safe
+                reloadPage();
+        }
+    }
+
+    /**
+     * Reload all stylesheets
+     */
+    function reloadStyles() {
+        console.log('%c[HMR] Reloading styles...', 'color: #2196F3;');
+
+        const links = document.querySelectorAll('link[rel="stylesheet"]');
+        links.forEach(link => {
+            const href = link.href.split('?')[0];
+            link.href = href + '?t=' + Date.now();
+        });
+
+        // Also reload inline styles if they reference external files
+        const styles = document.querySelectorAll('style');
+        styles.forEach(style => {
+            if (style.textContent.includes('@import')) {
+                style.textContent = style.textContent.replace(
+                    /\?t=\d+/g,
+                    `?t=${Date.now()}`
+                );
+            }
+        });
+
+        console.log('%c[HMR] Styles reloaded ✓', 'color: green;');
+    }
+
+    /**
+     * Reload a component by clearing its cache and refreshing
+     */
+    function reloadComponent(componentPath) {
+        console.log(`%c[HMR] Reloading component: ${componentPath}`, 'color: #FF9800;');
+
+        // Find all instances of the component in the DOM
+        const componentName = componentPath.split('-')[0];
+        const componentElements = document.querySelectorAll(`[data-hmr-component="${componentPath}"]`);
+
+        if (componentElements.length === 0) {
+            console.log('[HMR] Component not found in DOM, doing full reload');
+            reloadPage();
+            return;
+        }
+
+        // For Web Components, we need to reload the entire page
+        // because ES modules have singleton nature
+        reloadPage();
+    }
+
+    /**
+     * Perform full page reload
+     */
+    function reloadPage() {
+        console.log('%c[HMR] Performing full page reload...', 'color: #FF5722; font-weight: bold;');
+        
+        // Add query param to bust cache
+        const url = new URL(window.location);
+        url.searchParams.set('hmr', Date.now());
+        
+        // Use replace instead of reload to avoid adding history entries
+        window.location.replace(url.toString());
+    }
+
+    /**
+     * Initialize HMR client
+     */
+    function init() {
+        console.log('%c[AfriCode HMR Client] Initializing...', 'color: #673AB7; font-weight: bold;');
+        connect();
+    }
+
+    // Initialize when DOM is ready
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', init);
+    } else {
+        init();
+    }
+
+    // Cleanup on page unload
+    window.addEventListener('beforeunload', () => {
+        if (ws) {
+            ws.close();
+        }
+    });
+})();

package/core/hmr.js

@@ -0,0 +1,196 @@
+/**
+ * HMR Server - Hot Module Replacement for AfriCode
+ * 
+ * Provides:
+ * - WebSocket server for dev clients
+ * - File watcher for source changes
+ * - Module update broadcasting
+ * - Graceful reload handling
+ */
+
+import * as nodePath from 'node:path';
+import { watch } from 'node:fs';
+
+export class HMRServer {
+    constructor(port = 3001) {
+        this.port = port;
+        this.clients = new Set();
+        this.watchers = new Map();
+        this.fileChanges = new Map();
+    }
+
+    /**
+     * Start HMR WebSocket server
+     */
+    start(devServer) {
+        const hmrPort = this.port;
+        
+        // Upgrade HTTP connections to WebSocket
+        devServer.upgrade({
+            open(ws) {
+                console.log(`[HMR] Client connected from ${ws.remoteAddress}`);
+                this.clients.add(ws);
+            },
+            message(ws, message) {
+                // Handle ping/pong and client messages
+                try {
+                    const data = JSON.parse(message);
+                    if (data.type === 'ping') {
+                        ws.send(JSON.stringify({ type: 'pong' }));
+                    }
+                } catch (e) {
+                    // Invalid message, ignore
+                }
+            },
+            close(ws) {
+                this.clients.delete(ws);
+                console.log(`[HMR] Client disconnected`);
+            }
+        });
+
+        // Start file watching
+        this.watchDirectory(process.cwd());
+        console.log(`[HMR] Watching for changes...`);
+    }
+
+    /**
+     * Watch directory for changes recursively
+     */
+    watchDirectory(dir, prefix = '') {
+        const ignoreDirs = new Set([
+            'node_modules', '.git', 'dist', '.bun', 'build',
+            '.next', 'coverage', 'test-results'
+        ]);
+
+        try {
+            const watcher = watch(dir, { recursive: true }, (eventType, filename) => {
+                if (!filename) return;
+
+                const fullPath = nodePath.join(dir, filename);
+                const dirName = nodePath.dirname(filename);
+
+                // Ignore node_modules, build files, etc.
+                if (ignoreDirs.has(dirName.split(nodePath.sep)[0])) return;
+                if (filename.includes('node_modules')) return;
+                if (filename.endsWith('.test.js')) return;
+
+                // Only watch JS, JSX, TS, TSX, CSS, HTML
+                const validExts = ['.js', '.jsx', '.ts', '.tsx', '.css', '.html'];
+                if (!validExts.some(ext => filename.endsWith(ext))) return;
+
+                // Debounce rapid changes
+                const changeKey = fullPath;
+                if (this.fileChanges.has(changeKey)) {
+                    clearTimeout(this.fileChanges.get(changeKey));
+                }
+
+                const timeoutId = setTimeout(() => {
+                    this.handleFileChange(filename, fullPath);
+                    this.fileChanges.delete(changeKey);
+                }, 100);
+
+                this.fileChanges.set(changeKey, timeoutId);
+            });
+
+            this.watchers.set(dir, watcher);
+        } catch (err) {
+            console.error(`[HMR] Failed to watch ${dir}:`, err.message);
+        }
+    }
+
+    /**
+     * Handle file change - determine type and broadcast update
+     */
+    handleFileChange(filename, fullPath) {
+        const ext = nodePath.extname(filename);
+        const relativePath = nodePath.relative(process.cwd(), fullPath);
+        const normalizedPath = relativePath.replace(/\\/g, '/'); // Normalize Windows paths
+
+        // Filter out ignored files
+        if (normalizedPath.includes('node_modules')) return;
+        if (normalizedPath.includes('.test.')) return;
+        if (normalizedPath.includes('test/')) return;
+
+        console.log(`[HMR] File changed: ${normalizedPath}`);
+
+        // Determine module type and extract clean path
+        let moduleType = 'unknown';
+        let modulePath = normalizedPath;
+
+        if (normalizedPath.includes('pages/') && (ext === '.js' || ext === '.html')) {
+            moduleType = 'page';
+            // Extract just the page name from the path
+            const match = normalizedPath.match(/pages\/([^/]+)/);
+            modulePath = match ? match[1].replace(ext, '') : normalizedPath;
+        } else if (normalizedPath.includes('components/') && ext === '.js') {
+            moduleType = 'component';
+            // Extract just the component name
+            const match = normalizedPath.match(/components\/([^/]+)/);
+            modulePath = match ? match[1].replace(ext, '') : normalizedPath;
+        } else if (normalizedPath.includes('core/') && ext === '.js') {
+            moduleType = 'core';
+            // Extract just the module name
+            const match = normalizedPath.match(/core\/([^/]+)/);
+            modulePath = match ? match[1].replace(ext, '') : normalizedPath;
+        } else if (ext === '.css') {
+            moduleType = 'style';
+        } else if (ext === '.html') {
+            moduleType = 'markup';
+        }
+
+        // Broadcast change to all connected clients
+        this.broadcast({
+            type: 'update',
+            moduleType,
+            modulePath,
+            filename: normalizedPath,
+            timestamp: Date.now()
+        });
+    }
+
+    /**
+     * Broadcast message to all connected clients
+     */
+    broadcast(message) {
+        const payload = JSON.stringify(message);
+        let successCount = 0;
+
+        for (const client of this.clients) {
+            try {
+                client.send(payload);
+                successCount++;
+            } catch (err) {
+                // Client disconnected, will be cleaned up on next event
+            }
+        }
+
+        if (successCount > 0) {
+            console.log(`[HMR] Broadcasted update to ${successCount} client(s)`);
+        }
+    }
+
+    /**
+     * Stop all watchers and close WebSocket connections
+     */
+    stop() {
+        for (const watcher of this.watchers.values()) {
+            try {
+                watcher.close();
+            } catch (err) {
+                // Ignore close errors
+            }
+        }
+        this.watchers.clear();
+        this.clients.clear();
+        console.log(`[HMR] Server stopped`);
+    }
+}
+
+/**
+ * Create HMR server instance
+ */
+export function createHMRServer(port = 3001) {
+    return new HMRServer(port);
+}
+
+export default HMRServer;

package/core/html.d.ts

@@ -0,0 +1,116 @@
+/**
+ * AfriCode HTML Template Engine - TypeScript Definitions
+ * JSX-free template literal engine
+ */
+
+/**
+ * HTML template tag function
+ * Safely renders template literals as HTML strings
+ * 
+ * Usage:
+ * ```ts
+ * const name = 'Alice';
+ * const result = html`<h1>Hello ${name}</h1>`;
+ * ```
+ * 
+ * @param strings - Template string parts
+ * @param values - Interpolated values
+ * @returns Rendered HTML string
+ */
+export function html(
+  strings: TemplateStringsArray,
+  ...values: any[]
+): string;
+
+/**
+ * Render options
+ */
+export interface RenderOptions {
+  /** Escape HTML special characters */
+  escape?: boolean;
+  /** Keep falsy values as string */
+  keepFalsy?: boolean;
+  /** Custom serializer */
+  serializer?: (value: any) => string;
+}
+
+/**
+ * Safe HTML rendering with custom options
+ */
+export function renderHtml(
+  strings: TemplateStringsArray,
+  values: any[],
+  options?: RenderOptions
+): string;
+
+/**
+ * Layout component props
+ */
+export interface LayoutProps {
+  /** Use vertical layout (default: horizontal) */
+  vertical?: boolean;
+  /** Spacing between items (px) */
+  gap?: number;
+  /** Vertical alignment */
+  align?: 'start' | 'center' | 'end' | 'stretch';
+  /** Horizontal justification */
+  justify?: 'start' | 'center' | 'end' | 'between' | 'around';
+  /** Additional CSS classes */
+  class?: string;
+  /** Inline styles */
+  style?: Record<string, string>;
+}
+
+/**
+ * Layout component class
+ */
+export class Layout {
+  constructor(props?: LayoutProps);
+  
+  /**
+   * Add child element or text
+   */
+  addChild(child: HTMLElement | string): this;
+  
+  /**
+   * Render to HTML element
+   */
+  render(): HTMLElement;
+  
+  /**
+   * Get HTML string representation
+   */
+  toString(): string;
+}
+
+/**
+ * Flex layout shorthand
+ */
+export function flex(
+  options?: LayoutProps
+): HTMLElement;
+
+/**
+ * Grid layout shorthand
+ */
+export function grid(
+  columnCount: number,
+  gap?: number
+): HTMLElement;
+
+/**
+ * Create safe text node
+ */
+export function text(content: string): string;
+
+/**
+ * Escape HTML entities
+ */
+export function escape(str: string): string;
+
+/**
+ * Unescape HTML entities
+ */
+export function unescape(str: string): string;
+
+export default html;

package/core/html.js

@@ -0,0 +1,160 @@
+/**
+ * AfriCode HTML Template Engine
+ * 
+ * Provides the `html` tagged template literal for writing markup in JavaScript.
+ * This is a lightweight, zero-compile template system (JSX alternative).
+ * 
+ * @module core/html
+ */
+
+/**
+ * RawHtml wrapper class
+ * Marks HTML content as safe and prevents escaping when interpolated
+ * 
+ * @class RawHtml
+ * @param {string} content - The raw HTML content
+ */
+export class RawHtml {
+  constructor(content) {
+    this.content = content;
+  }
+
+  toString() {
+    return this.content;
+  }
+
+  valueOf() {
+    return this.content;
+  }
+}
+
+/**
+ * Escape HTML special characters to prevent XSS
+ * 
+ * @param {any} str - Value to escape
+ * @returns {string} Escaped string
+ */
+function escapeHtml(str) {
+  if (typeof str !== 'string') {return str;}
+  
+  const map = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#039;'
+  };
+  
+  return str.replace(/[&<>"']/g, char => map[char]);
+}
+
+/**
+ * Safely interpolate a value into HTML
+ * - If RawHtml: insert as raw markup
+ * - If array: recursively process and join
+ * - If null/undefined/false: render empty string
+ * - Otherwise: escape as text
+ * 
+ * @param {any} value - Value to interpolate
+ * @returns {string}
+ */
+function interpolateValue(value) {
+  // RawHtml: insert as raw markup (safe for nested templates)
+  if (value instanceof RawHtml) {
+    return value.toString();
+  }
+  
+  // Arrays: recursively process and join
+  if (Array.isArray(value)) {
+    return value.map(v => interpolateValue(v)).join('');
+  }
+  
+  // Falsy values: render empty string
+  if (value === null || value === undefined || value === false) {
+    return '';
+  }
+  
+  // Functions: convert to string (for component functions, better to call them first)
+  if (typeof value === 'function') {
+    return escapeHtml(String(value));
+  }
+  
+  // Everything else: escape as text
+  return escapeHtml(String(value));
+}
+
+/**
+ * Tagged template literal for HTML
+ * Safely handles nested templates, arrays, and text escaping.
+ * 
+ * Returns a RawHtml wrapper so nested templates aren't double-escaped.
+ * 
+ * @param {TemplateStringsArray} strings 
+ * @param  {...any} values 
+ * @returns {RawHtml}
+ * 
+ * @example
+ * // Nested templates (no escaping of markup)
+ * const button = html`<af-button>Click</af-button>`;
+ * const page = html`<div>${button}</div>`;
+ * // Output: <div><af-button>Click</af-button></div>
+ * 
+ * @example
+ * // Plain text (escaped for safety)
+ * const user = html`<p>${userInput}</p>`;
+ * // If userInput = "<script>alert('xss')</script>"
+ * // Output: <p>&lt;script&gt;alert('xss')&lt;/script&gt;</p>
+ * 
+ * @example
+ * // Arrays of templates
+ * const items = [html`<li>Item 1</li>`, html`<li>Item 2</li>`];
+ * const list = html`<ul>${items}</ul>`;
+ * // Output: <ul><li>Item 1</li><li>Item 2</li></ul>
+ */
+export function html(strings, ...values) {
+    let result = '';
+
+    for (let i = 0; i < values.length; i++) {
+        result += strings[i];
+        result += interpolateValue(values[i]);
+    }
+
+    result += strings[strings.length - 1];
+    
+    // Return as RawHtml so nested html() calls aren't escaped
+    return new RawHtml(result);
+}
+
+/**
+ * Standard Root Layout
+ * Similar to Next.js layout.js concept
+ * 
+ * @param {Object} options
+ * @param {string} options.title - Page title
+ * @param {string} options.meta - Meta tags
+ * @param {RawHtml|string} options.children - Page content
+ * @returns {RawHtml}
+ */
+export function Layout({ title = 'AfriCode App', meta = '', children }) {
+    return html`<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${title}</title>
+    ${meta}
+    <link rel="stylesheet" href="/styles/africanity.css">
+    <script type="module" src="/core/sdk.js"></script>
+    <script type="module">
+        import { init } from '/core/sdk.js';
+        init();
+    </script>
+</head>
+<body>
+    ${children}
+</body>
+</html>`;
+}
+
+
+export default { html, Layout, RawHtml };