@africode/core 5.0.0

package/components/tooltip.js

@@ -0,0 +1,167 @@
+/**
+ * AfriCode Tooltip Component
+ * 
+ * Hover tooltips with positioning options.
+ * 
+ * @module components/tooltip
+ */
+
+import { AfriCodeComponent, registerComponent } from './base.js';
+
+export class AfriTooltip extends AfriCodeComponent {
+    static get observedAttributes() {
+        return ['text', 'position'];
+    }
+
+    constructor() {
+        super();
+        this._tooltipId = `af-tooltip-${Math.random().toString(36).substr(2, 9)}`;
+        this.render();
+    }
+
+    connectedCallback() {
+        this._setupTooltipListeners();
+    }
+
+    attributeChangedCallback() {
+        this.render();
+        this._setupTooltipListeners();
+    }
+
+    _setupTooltipListeners() {
+        const trigger = this.shadowRoot.querySelector('.tooltip-trigger');
+        const content = this.shadowRoot.querySelector('.tooltip-content');
+
+        if (!trigger || !content) {return;}
+
+        trigger.addEventListener('focus', () => {
+            content.style.opacity = '1';
+            content.style.visibility = 'visible';
+            content.setAttribute('aria-hidden', 'false');
+        });
+
+        trigger.addEventListener('blur', () => {
+            content.style.opacity = '0';
+            content.style.visibility = 'hidden';
+            content.setAttribute('aria-hidden', 'true');
+        });
+
+        trigger.addEventListener('mouseenter', () => {
+            content.style.opacity = '1';
+            content.style.visibility = 'visible';
+            content.setAttribute('aria-hidden', 'false');
+        });
+
+        trigger.addEventListener('mouseleave', () => {
+            content.style.opacity = '0';
+            content.style.visibility = 'hidden';
+            content.setAttribute('aria-hidden', 'true');
+        });
+    }
+
+    render() {
+        const text = this.getAttribute('text') || 'Tooltip';
+        const position = this.getAttribute('position') || 'top';
+
+        const positions = {
+            top: `
+        bottom: 100%;
+        left: 50%;
+        transform: translateX(-50%) translateY(-8px);
+      `,
+            bottom: `
+        top: 100%;
+        left: 50%;
+        transform: translateX(-50%) translateY(8px);
+      `,
+            left: `
+        right: 100%;
+        top: 50%;
+        transform: translateY(-50%) translateX(-8px);
+      `,
+            right: `
+        left: 100%;
+        top: 50%;
+        transform: translateY(-50%) translateX(8px);
+      `
+        };
+
+        this.shadowRoot.innerHTML = `
+      <style>
+        :host {
+          display: inline-block;
+          position: relative;
+          font-family: 'Inter', system-ui, sans-serif;
+        }
+
+        .tooltip-trigger {
+          display: inline-block;
+          cursor: help;
+        }
+
+        .tooltip-content {
+          position: absolute;
+          ${positions[position]}
+          padding: 8px 12px;
+          background: #1e1e1e;
+          border: 1px solid #2a2a2a;
+          border-radius: 6px;
+          color: #ffffff;
+          font-size: 0.85rem;
+          white-space: nowrap;
+          opacity: 0;
+          visibility: hidden;
+          transition: all 0.2s ease;
+          z-index: 1000;
+          box-shadow: 0 4px 20px rgba(0,0,0,0.4);
+        }
+
+        .tooltip-trigger:hover + .tooltip-content,
+        .tooltip-trigger:focus + .tooltip-content,
+        .tooltip-content:hover {
+          opacity: 1;
+          visibility: visible;
+        }
+
+        /* Arrow */
+        .tooltip-content::after {
+          content: '';
+          position: absolute;
+          border: 6px solid transparent;
+          ${position === 'top' ? `
+            top: 100%;
+            left: 50%;
+            transform: translateX(-50%);
+            border-top-color: #1e1e1e;
+          ` : ''}
+          ${position === 'bottom' ? `
+            bottom: 100%;
+            left: 50%;
+            transform: translateX(-50%);
+            border-bottom-color: #1e1e1e;
+          ` : ''}
+          ${position === 'left' ? `
+            left: 100%;
+            top: 50%;
+            transform: translateY(-50%);
+            border-left-color: #1e1e1e;
+          ` : ''}
+          ${position === 'right' ? `
+            right: 100%;
+            top: 50%;
+            transform: translateY(-50%);
+            border-right-color: #1e1e1e;
+          ` : ''}
+        }
+      </style>
+
+      <span class="tooltip-trigger" tabindex="0" aria-describedby="${this._tooltipId}">
+        <slot></slot>
+      </span>
+      <div class="tooltip-content" id="${this._tooltipId}" role="tooltip" aria-hidden="true">${text}</div>
+    `;
+    }
+}
+
+registerComponent('af-tooltip', AfriTooltip);
+export default AfriTooltip;

package/core/a2ui-schema-manager.js

@@ -0,0 +1,344 @@
+/**
+ * A2UI Schema Manager
+ * Generates and validates component manifest for AI agent consumption
+ * 
+ * This ensures AI agents only generate code using pre-approved, safe components
+ * Prevents hallucination of raw HTML/JavaScript
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export class A2UISchemaManager {
+    constructor(componentDir = './components') {
+        this.componentDir = componentDir;
+        this.schema = {
+            version: '5.0.0',
+            timestamp: new Date().toISOString(),
+            components: [],
+            patterns: this.getEthnomathematicalPatterns(),
+            forbiddenPatterns: [
+                'eval()',
+                'innerHTML = userInput',
+                'fetch without CORS headers',
+                'localStorage for sensitive data',
+                'document.domain manipulation',
+                'postMessage without origin check'
+            ],
+            constraintRules: [
+                'All dynamic content must use Web Components',
+                'No raw HTML generation outside of Shadow DOM',
+                'All user input must be validated with schemas',
+                'All network requests must include CORS headers',
+                'All fintech operations must call compliance middleware',
+                'All identity operations must use NIDA CIG endpoints',
+                'All payments must be processed through TIPS',
+                'All transactions must be logged for AML/FIU reporting'
+            ]
+        };
+    }
+
+    /**
+     * Ethnomathematical pattern generation rules
+     * Encodes African fractal geometry and cultural weaving algorithms
+     */
+    getEthnomathematicalPatterns() {
+        return {
+            kente: {
+                name: 'Kente Weaving',
+                algorithm: 'glide_reflection',
+                parameters: {
+                    baseColor: { type: 'string', pattern: '^#[0-9a-fA-F]{6}$' },
+                    accentColor: { type: 'string', pattern: '^#[0-9a-fA-F]{6}$' },
+                    width: { type: 'number', min: 100, max: 1000 },
+                    height: { type: 'number', min: 100, max: 1000 },
+                    complexity: { type: 'number', min: 1, max: 5 }
+                },
+                rules: [
+                    'Use glide reflection symmetry (translation + reflection)',
+                    'Maintain golden ratio proportions',
+                    'Alternate colors in checkerboard pattern',
+                    'Apply fractal scaling for complexity levels'
+                ],
+                usage: 'Cultural textiles, ceremonial garments, digital art'
+            },
+            shuka: {
+                name: 'Maasai Shuka Tartan',
+                algorithm: 'strip_weaving',
+                parameters: {
+                    primaryColor: { type: 'string', pattern: '^#[0-9a-fA-F]{6}$' },
+                    secondaryColor: { type: 'string', pattern: '^#[0-9a-fA-F]{6}$' },
+                    stripeWidth: { type: 'number', min: 5, max: 50 },
+                    pattern: { type: 'string', enum: ['horizontal', 'vertical', 'diagonal', 'plaid'] },
+                    borderWidth: { type: 'number', min: 1, max: 10 }
+                },
+                rules: [
+                    'Use strip weaving technique with color alternation',
+                    'Maintain consistent stripe proportions',
+                    'Apply border framing for cultural authenticity',
+                    'Use earthy color palettes (reds, blacks, whites)'
+                ],
+                usage: 'Traditional garments, cultural identity, modern fashion'
+            },
+            ndebele: {
+                name: 'Ndebele Geometric Fractals',
+                algorithm: 'recursive_geometry',
+                parameters: {
+                    baseColor: { type: 'string', pattern: '^#[0-9a-fA-F]{6}$' },
+                    accentColors: { type: 'array', items: { type: 'string', pattern: '^#[0-9a-fA-F]{6}$' }, maxItems: 4 },
+                    recursionDepth: { type: 'number', min: 1, max: 4 },
+                    symmetry: { type: 'string', enum: ['rotational', 'reflection', 'translational'] },
+                    scale: { type: 'number', min: 0.1, max: 2.0 }
+                },
+                rules: [
+                    'Apply recursive geometric subdivision',
+                    'Use rotational symmetry around center points',
+                    'Maintain fractal self-similarity at all scales',
+                    'Incorporate traditional Ndebele color symbolism'
+                ],
+                usage: 'Wall art, beadwork, architectural decoration, digital design'
+            },
+            kitenge: {
+                name: 'Kitenge Floral Patterns',
+                algorithm: 'organic_growth',
+                parameters: {
+                    backgroundColor: { type: 'string', pattern: '^#[0-9a-fA-F]{6}$' },
+                    floralColors: { type: 'array', items: { type: 'string', pattern: '^#[0-9a-fA-F]{6}$' }, minItems: 2, maxItems: 6 },
+                    density: { type: 'number', min: 0.1, max: 1.0 },
+                    scale: { type: 'number', min: 0.5, max: 2.0 },
+                    symmetry: { type: 'boolean', default: true }
+                },
+                rules: [
+                    'Use organic growth algorithms for natural forms',
+                    'Apply bilateral symmetry for traditional aesthetics',
+                    'Vary density for different fabric weights',
+                    'Maintain cultural color significance (greens, blues, earth tones)'
+                ],
+                usage: 'Textile printing, fashion design, home decor, cultural products'
+            }
+        };
+    }
+
+    /**
+     * Scan components directory and extract metadata
+     */
+    async scanComponents() {
+        const files = fs.readdirSync(this.componentDir).filter(f => 
+            f.endsWith('.js') && !f.startsWith('.')
+        );
+
+        for (const file of files) {
+            const filePath = path.join(this.componentDir, file);
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const metadata = this.extractComponentMetadata(file, content);
+            
+            if (metadata) {
+                this.schema.components.push(metadata);
+            }
+        }
+
+        return this.schema;
+    }
+
+    /**
+     * Extract component metadata from source code
+     * Looks for JSDoc comments and Web Component definition
+     */
+    extractComponentMetadata(filename, content) {
+        // Extract tagName
+        const tagMatch = content.match(/customElements\.define\(['"]([a-z0-9-]+)['"]/);
+        if (!tagMatch) return null;
+
+        const tagName = tagMatch[1];
+
+        // Extract slots
+        const slotMatches = [...content.matchAll(/<slot[^>]*name=['"]([^'"]+)['"]/g)];
+        const slots = slotMatches.map(m => m[1]);
+
+        // Extract attributes from constructor/connectedCallback
+        const attrMatches = [...content.matchAll(/this\.getAttribute\(['"]([^'"]+)['"]\)/g)];
+        const attributes = {};
+        attrMatches.forEach(m => {
+            attributes[m[1]] = { type: 'string', required: false };
+        });
+
+        // Extract events from dispatchEvent calls
+        const eventMatches = [...content.matchAll(/dispatchEvent\(\s*new\s+CustomEvent\(['"]([^'"]+)['"]/g)];
+        const events = eventMatches.map(m => ({
+            name: m[1],
+            detail: { type: 'object' }
+        }));
+
+        // Extract CSS custom properties
+        const cssMatches = [...content.matchAll(/var\(['--([a-z0-9-]+)['"\)]/g)];
+        const cssCustomProperties = cssMatches.map(m => '--' + m[1]);
+
+        // Extract JSDoc comments
+        const jsdocMatch = content.match(/\/\*\*[\s\S]*?\*\//);
+        const description = jsdocMatch ? jsdocMatch[0] : '';
+
+        return {
+            tagName,
+            filePath: `components/${filename}`,
+            description: description.substring(0, 200),
+            slots,
+            attributes,
+            events,
+            cssCustomProperties: [...new Set(cssCustomProperties)],
+            example: `<${tagName}>Content</${tagName}>`,
+            securityNotes: 'Sanitizes slot content'
+        };
+    }
+
+    /**
+     * Validate proposed HTML against schema
+     * Ensures code only uses approved components
+     */
+    validateHTML(html) {
+        const errors = [];
+        const warnings = [];
+
+        // Extract all custom elements used
+        const componentMatches = [...html.matchAll(/<(af-[a-z0-9-]+)/g)];
+        const usedComponents = new Set(componentMatches.map(m => m[1]));
+
+        // Check against approved components
+        const approvedTags = this.schema.components.map(c => c.tagName);
+        for (const tag of usedComponents) {
+            if (!approvedTags.includes(tag)) {
+                errors.push(`Unknown component: <${tag}> — not in COMPONENT_SCHEMA`);
+            }
+        }
+
+        // Check for forbidden patterns
+        for (const pattern of this.schema.forbiddenPatterns) {
+            if (pattern === 'eval()') {
+                if (/eval\s*\(/i.test(html)) {
+                    errors.push('Forbidden: eval() detected');
+                }
+            } else if (pattern === 'innerHTML = userInput') {
+                if (/innerHTML\s*=\s*(?!`[^`]*<[a-z]/i.test(html)) {
+                    warnings.push('Warning: innerHTML assignment detected — ensure content is sanitized');
+                }
+            }
+        }
+
+        return { valid: errors.length === 0, errors, warnings };
+    }
+
+    /**
+     * Generate and save the complete A2UI catalog
+     */
+    async generateManifest(outputPath = './catalog.json') {
+        console.log('🤖 Generating A2UI component catalog...');
+
+        // Scan components
+        await this.scanComponents();
+
+        // Add pattern generation hints
+        this.schema.usageHints = {
+            components: {
+                'af-button': 'Use for primary/secondary actions, always include accessibility labels',
+                'af-card': 'Use for content containers, supports cultural card variants',
+                'af-form': 'Use for data collection, automatically validates with schemas',
+                'af-nida-verify': 'Use for identity verification, requires NIDA CIG compliance',
+                'af-payment-form': 'Use for payments, automatically handles TIPS processing',
+                'af-cultural-card': 'Use for cultural content, supports pattern overlays'
+            },
+            patterns: {
+                'kente': 'Use for formal/cultural contexts, high complexity for ceremonies',
+                'shuka': 'Use for traditional Maasai designs, earthy color palettes',
+                'ndebele': 'Use for geometric art, recursive depth for complexity',
+                'kitenge': 'Use for floral patterns, organic growth for natural feel'
+            },
+            constraints: [
+                'Always use af-* components instead of raw HTML',
+                'Validate all user input with schema rules',
+                'Include cultural context in component selection',
+                'Ensure fintech operations call compliance middleware',
+                'Use appropriate ethnomathematical patterns for cultural authenticity'
+            ]
+        };
+
+        // Save catalog
+        fs.writeFileSync(outputPath, JSON.stringify(this.schema, null, 2));
+        console.log(`✅ A2UI catalog generated: ${outputPath}`);
+
+        return this.schema;
+    }
+        const component = this.schema.components.find(c => c.tagName === tagName);
+        if (!component) {
+            return { valid: false, error: `Component ${tagName} not found in schema` };
+        }
+
+        const errors = [];
+
+        // Check required attributes
+        for (const [attr, config] of Object.entries(component.attributes)) {
+            if (config.required && !(attr in props)) {
+                errors.push(`Missing required attribute: ${attr}`);
+            }
+
+            // Validate attribute value if needed
+            if (attr in props && config.pattern) {
+                const regex = new RegExp(config.pattern);
+                if (!regex.test(props[attr])) {
+                    errors.push(`Attribute ${attr} does not match pattern: ${config.pattern}`);
+                }
+            }
+        }
+
+        return { valid: errors.length === 0, errors };
+    }
+
+    /**
+     * Generate TypeScript type definitions for components
+     */
+    generateTypeDefinitions() {
+        let defs = '// Auto-generated AfriCode Component Types\n\n';
+
+        for (const component of this.schema.components) {
+            defs += `export interface ${this.toCamelCase(component.tagName)}Props {\n`;
+            
+            for (const [attr, config] of Object.entries(component.attributes)) {
+                const optional = !config.required ? '?' : '';
+                defs += `  ${attr}${optional}: ${config.type};\n`;
+            }
+
+            defs += `}\n\n`;
+        }
+
+        return defs;
+    }
+
+    /**
+     * Export schema to JSON file
+     */
+    async exportSchema(filePath = './COMPONENT_SCHEMA.json') {
+        fs.writeFileSync(filePath, JSON.stringify(this.schema, null, 2));
+        console.log(`✅ Component schema exported to ${filePath}`);
+    }
+
+    /**
+     * Utility: Convert kebab-case to camelCase
+     */
+    toCamelCase(str) {
+        return str.replace(/-./g, x => x[1].toUpperCase());
+    }
+}
+
+/**
+ * CLI Usage
+ * node core/a2ui-schema-manager.js generate
+ */
+if (import.meta.main) {
+    const manager = new A2UISchemaManager('./components');
+    
+    (async () => {
+        await manager.scanComponents();
+        await manager.exportSchema();
+        console.log(`📋 Schema contains ${manager.schema.components.length} approved components`);
+    })();
+}
+
+export default A2UISchemaManager;