@africode/core 5.0.0

package/core/a2ui.js

@@ -0,0 +1,431 @@
+/**
+ * A2UI Protocol Implementation
+ * Agent-to-User Interface declarative protocol for generative AI
+ *
+ * Enables AI agents to return UI widgets as part of responses without
+ * executing arbitrary code, ensuring security and consistency.
+ *
+ * @module core/a2ui
+ */
+
+/**
+ * A2UI Message Types
+ */
+export const A2UI_TYPES = {
+    COMPONENT: 'component',
+    FORM: 'form',
+    LIST: 'list',
+    CARD: 'card',
+    MODAL: 'modal',
+    TOAST: 'toast',
+    PROGRESS: 'progress'
+};
+
+/**
+ * A2UI Component Schemas
+ */
+export const A2UI_SCHEMAS = {
+    component: {
+        type: 'object',
+        properties: {
+            id: { type: 'string' },
+            type: { type: 'string', enum: Object.values(A2UI_TYPES) },
+            props: { type: 'object' },
+            children: { type: 'array', items: { $ref: '#' } }
+        },
+        required: ['id', 'type']
+    }
+};
+
+/**
+ * A2UI Renderer
+ * Renders A2UI messages into actual DOM elements
+ */
+export class A2UIRenderer {
+    constructor(rootElement) {
+        this.root = rootElement;
+        this.components = new Map();
+    }
+
+    /**
+     * Render an A2UI message
+     * @param {Object} message - A2UI message object
+     */
+    async render(message) {
+        if (!message || !message.type) {
+            throw new Error('Invalid A2UI message');
+        }
+
+        const canRenderToDOM = this.root && typeof this.root.appendChild === 'function';
+
+        if (!canRenderToDOM) {
+            const placeholder = {
+                id: message.id || `a2ui-${Date.now()}`,
+                type: message.type,
+                props: message.props || {},
+                children: message.children || []
+            };
+
+            if (placeholder.id) {
+                this.components.set(placeholder.id, placeholder);
+            }
+
+            return placeholder;
+        }
+
+        const element = await this.createElement(message);
+        this.root.appendChild(element);
+        return element;
+    }
+
+    /**
+     * Create DOM element from A2UI component
+     * @param {Object} component - A2UI component definition
+     */
+    async createElement(component) {
+        const { type, props = {}, children = [] } = component;
+
+        let element;
+
+        switch (type) {
+            case A2UI_TYPES.COMPONENT:
+                element = await this.createCustomComponent(props);
+                break;
+            case A2UI_TYPES.FORM:
+                element = await this.createForm(props);
+                break;
+            case A2UI_TYPES.LIST:
+                element = await this.createList(props);
+                break;
+            case A2UI_TYPES.CARD:
+                element = await this.createCard(props);
+                break;
+            case A2UI_TYPES.MODAL:
+                element = await this.createModal(props);
+                break;
+            case A2UI_TYPES.TOAST:
+                element = await this.createToast(props);
+                break;
+            case A2UI_TYPES.PROGRESS:
+                element = await this.createProgress(props);
+                break;
+            default:
+                throw new Error(`Unknown A2UI component type: ${type}`);
+        }
+
+        // Render children
+        if (children.length > 0) {
+            for (const child of children) {
+                const childElement = await this.createElement(child);
+                element.appendChild(childElement);
+            }
+        }
+
+        return element;
+    }
+
+    /**
+     * Create custom AfriCode component
+     */
+    async createCustomComponent({ tag, ...props }) {
+        const element = document.createElement(tag || 'div');
+        Object.assign(element, props);
+        return element;
+    }
+
+    /**
+     * Create form component
+     */
+    async createForm({ fields = [], onSubmit }) {
+        const form = document.createElement('af-form');
+
+        for (const field of fields) {
+            const input = document.createElement('af-input');
+            input.setAttribute('name', field.name);
+            input.setAttribute('placeholder', field.placeholder || '');
+            input.setAttribute('type', field.type || 'text');
+            form.appendChild(input);
+        }
+
+        if (onSubmit) {
+            form.addEventListener('submit', onSubmit);
+        }
+
+        return form;
+    }
+
+    /**
+     * Create list component
+     */
+    async createList({ items = [] }) {
+        const list = document.createElement('af-grid');
+
+        for (const item of items) {
+            const card = await this.createCard(item);
+            list.appendChild(card);
+        }
+
+        return list;
+    }
+
+    /**
+     * Create card component
+     */
+    async createCard({ title, content, image }) {
+        const card = document.createElement('af-card');
+
+        if (title) {
+            const titleEl = document.createElement('h3');
+            titleEl.textContent = title;
+            card.appendChild(titleEl);
+        }
+
+        if (content) {
+            const contentEl = document.createElement('p');
+            contentEl.textContent = content;
+            card.appendChild(contentEl);
+        }
+
+        if (image) {
+            const img = document.createElement('img');
+            img.src = image;
+            img.alt = title || 'Card image';
+            card.appendChild(img);
+        }
+
+        return card;
+    }
+
+    /**
+     * Create modal component
+     */
+    async createModal({ title, content, actions = [] }) {
+        const modal = document.createElement('af-modal');
+        modal.setAttribute('open', '');
+
+        if (title) {
+            const titleEl = document.createElement('h2');
+            titleEl.slot = 'header';
+            titleEl.textContent = title;
+            modal.appendChild(titleEl);
+        }
+
+        if (content) {
+            const contentEl = document.createElement('p');
+            contentEl.textContent = content;
+            modal.appendChild(contentEl);
+        }
+
+        const actionsContainer = document.createElement('div');
+        actionsContainer.slot = 'footer';
+
+        for (const action of actions) {
+            const button = document.createElement('af-button');
+            button.textContent = action.label;
+            if (action.primary) {
+                button.setAttribute('variant', 'primary');
+            }
+            if (action.onClick) {
+                button.addEventListener('click', action.onClick);
+            }
+            actionsContainer.appendChild(button);
+        }
+
+        modal.appendChild(actionsContainer);
+        return modal;
+    }
+
+    /**
+     * Create toast component
+     */
+    async createToast({ message, type = 'info', duration = 3000 }) {
+        const toast = document.createElement('af-toast');
+        toast.setAttribute('type', type);
+        toast.textContent = message;
+
+        // Auto-remove after duration
+        setTimeout(() => {
+            toast.remove();
+        }, duration);
+
+        return toast;
+    }
+
+    /**
+     * Create progress component
+     */
+    async createProgress({ value = 0, max = 100, label }) {
+        const progress = document.createElement('af-progress');
+        progress.setAttribute('value', value);
+        progress.setAttribute('max', max);
+
+        if (label) {
+            progress.setAttribute('label', label);
+        }
+
+        return progress;
+    }
+
+    /**
+     * Update existing component
+     */
+    async update(id, newProps) {
+        const element = this.components.get(id);
+        if (element) {
+            Object.assign(element, newProps);
+        }
+    }
+
+    /**
+     * Remove component
+     */
+    remove(id) {
+        const element = this.components.get(id);
+        if (element) {
+            element.remove();
+            this.components.delete(id);
+        }
+    }
+}
+
+/**
+ * A2UI Protocol Handler
+ * Processes streaming A2UI messages from AI agents
+ */
+export class A2UIProtocol {
+    constructor(renderer) {
+        this.renderer = renderer;
+        this.messageQueue = [];
+        this.messageHandlers = [];
+        this.isProcessing = false;
+    }
+
+    /**
+     * Register a message handler callback
+     * @param {Function} callback - Handler to receive processed messages
+     */
+    onMessage(callback) {
+        if (typeof callback === 'function') {
+            this.messageHandlers.push(callback);
+        }
+    }
+
+    /**
+     * Send a message into the A2UI system
+     * @param {Object|string} message - A2UI message
+     */
+    async sendMessage(message) {
+        return this.processMessage(message);
+    }
+
+    /**
+     * Process incoming A2UI message
+     * @param {Object|string} message - A2UI message
+     */
+    async processMessage(message) {
+        if (typeof message === 'string') {
+            try {
+                message = JSON.parse(message);
+            } catch {
+                console.warn('Invalid A2UI message format:', message);
+                return;
+            }
+        }
+
+        this.messageQueue.push(message);
+        await this.processQueue();
+
+        for (const handler of this.messageHandlers) {
+            handler(message);
+        }
+    }
+
+    /**
+     * Process queued messages
+     */
+    async processQueue() {
+        if (this.isProcessing || this.messageQueue.length === 0) {
+            return;
+        }
+
+        this.isProcessing = true;
+
+        while (this.messageQueue.length > 0) {
+            const message = this.messageQueue.shift();
+
+            try {
+                await this.renderer.render(message);
+            } catch (error) {
+                console.error('A2UI render error:', error);
+            }
+        }
+
+        this.isProcessing = false;
+    }
+
+    /**
+     * Stream handler for real-time AI responses
+     * @param {ReadableStream} stream - AI response stream
+     */
+    async handleStream(stream) {
+        const reader = stream.getReader();
+        const decoder = new TextDecoder();
+
+        let buffer = '';
+
+        while (true) {
+            const { done, value } = await reader.read();
+
+            if (done) {
+                break;
+            }
+
+            buffer += decoder.decode(value, { stream: true });
+
+            // Process complete messages
+            const messages = buffer.split('\n');
+            buffer = messages.pop(); // Keep incomplete message in buffer
+
+            for (const message of messages) {
+                if (message.trim()) {
+                    await this.processMessage(message.trim());
+                }
+            }
+        }
+
+        // Process any remaining buffer
+        if (buffer.trim()) {
+            await this.processMessage(buffer.trim());
+        }
+    }
+}
+
+/**
+ * Initialize A2UI system
+ * @param {HTMLElement} root - Root element for rendering
+ */
+export function initA2UI(root) {
+    // Handle server-side rendering (no DOM)
+    if (typeof document === 'undefined') {
+        root = null;
+    } else {
+        root = root || document.body;
+    }
+
+    const renderer = new A2UIRenderer(root);
+    const protocol = new A2UIProtocol(renderer);
+
+    // Make globally available for AI agents
+    if (typeof window !== 'undefined') {
+        window.a2ui = {
+            render: (message) => protocol.processMessage(message),
+            handleStream: (stream) => protocol.handleStream(stream),
+            update: (id, props) => renderer.update(id, props),
+            remove: (id) => renderer.remove(id),
+            sendMessage: (message) => protocol.sendMessage(message),
+            onMessage: (callback) => protocol.onMessage(callback)
+        };
+    }
+
+    return { renderer, protocol };
+}