@africode/core 5.0.0

package/components/avatar.js

@@ -0,0 +1,117 @@
+/**
+ * AfriCode Avatar Component
+ * 
+ * User profile images and initials with status indicators.
+ * Suitable for: User profiles, Comments, Team members, Chat
+ * 
+ * @module components/avatar
+ */
+
+import { AfriCodeComponent, registerComponent } from './base.js';
+
+export class AfriAvatar extends AfriCodeComponent {
+    static get observedAttributes() {
+        return ['src', 'name', 'size', 'status', 'theme'];
+    }
+
+    constructor() {
+        super();
+        this.render();
+    }
+
+    attributeChangedCallback() {
+        this.render();
+    }
+
+    _getInitials(name) {
+        if (!name) {return '?';}
+        const parts = name.trim().split(' ');
+        if (parts.length >= 2) {
+            return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase();
+        }
+        return name.substring(0, 2).toUpperCase();
+    }
+
+    render() {
+        const src = this.getAttribute('src');
+        const name = this.getAttribute('name') || '';
+        const size = this.getAttribute('size') || 'md';
+        const status = this.getAttribute('status');
+        const theme = this.getAttribute('theme') || 'tanzania';
+
+        const themes = {
+            tanzania: '#1EB53A',
+            maasai: '#FF0000',
+            ndebele: '#4169E1',
+            gold: '#FCD116'
+        };
+        const bgColor = themes[theme] || themes.tanzania;
+
+        const sizes = {
+            sm: { size: '32px', font: '12px', status: '8px' },
+            md: { size: '44px', font: '16px', status: '10px' },
+            lg: { size: '64px', font: '22px', status: '14px' },
+            xl: { size: '96px', font: '32px', status: '18px' }
+        };
+        const s = sizes[size] || sizes.md;
+
+        const statusColors = {
+            online: '#28a745',
+            offline: '#6c757d',
+            busy: '#dc3545',
+            away: '#ffc107'
+        };
+
+        this.shadowRoot.innerHTML = `
+      <style>
+        :host {
+          display: inline-block;
+          font-family: 'Inter', system-ui, sans-serif;
+        }
+
+        .avatar {
+          position: relative;
+          width: ${s.size};
+          height: ${s.size};
+          border-radius: 50%;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          background: ${bgColor};
+          color: white;
+          font-weight: 600;
+          font-size: ${s.font};
+          overflow: hidden;
+        }
+
+        .avatar img {
+          width: 100%;
+          height: 100%;
+          object-fit: cover;
+        }
+
+        .status {
+          position: absolute;
+          bottom: 0;
+          right: 0;
+          width: ${s.status};
+          height: ${s.status};
+          border-radius: 50%;
+          border: 2px solid white;
+          background: ${status ? statusColors[status] || statusColors.offline : 'transparent'};
+        }
+      </style>
+
+      <div class="avatar" title="${name}">
+        ${src
+                ? `<img src="${src}" alt="${name}" />`
+                : this._getInitials(name)
+            }
+        ${status ? '<span class="status"></span>' : ''}
+      </div>
+    `;
+    }
+}
+
+registerComponent('af-avatar', AfriAvatar);
+export default AfriAvatar;

package/components/badge.js

@@ -0,0 +1,104 @@
+/**
+ * AfriCode Badge/Tag Component
+ * 
+ * Status indicators, labels, and tags.
+ * Suitable for: E-commerce (product tags), Healthcare (status), Finance (categories)
+ * 
+ * @module components/badge
+ */
+
+import { AfriCodeComponent, registerComponent } from './base.js';
+
+export class AfriBadge extends AfriCodeComponent {
+    static get observedAttributes() {
+        return ['variant', 'size', 'removable'];
+    }
+
+    constructor() {
+        super();
+        this.render();
+    }
+
+    connectedCallback() {
+        this.shadowRoot.querySelector('.remove-btn')?.addEventListener('click', () => {
+            this.emit('af-remove');
+            this.remove();
+        });
+    }
+
+    attributeChangedCallback() {
+        this.render();
+    }
+
+    render() {
+        const variant = this.getAttribute('variant') || 'default';
+        const size = this.getAttribute('size') || 'md';
+        const removable = this.hasAttribute('removable');
+
+        const variants = {
+            default: { bg: '#e9ecef', text: '#495057' },
+            success: { bg: '#d4edda', text: '#155724' },
+            warning: { bg: '#fff3cd', text: '#856404' },
+            error: { bg: '#f8d7da', text: '#721c24' },
+            info: { bg: '#d1ecf1', text: '#0c5460' },
+            tanzania: { bg: '#1EB53A', text: '#FFFFFF' },
+            maasai: { bg: '#FF0000', text: '#FFFFFF' },
+            ndebele: { bg: '#4169E1', text: '#FFFFFF' },
+            gold: { bg: '#FCD116', text: '#000000' }
+        };
+        const v = variants[variant] || variants.default;
+
+        const sizes = {
+            sm: { padding: '2px 6px', fontSize: '11px' },
+            md: { padding: '4px 10px', fontSize: '13px' },
+            lg: { padding: '6px 14px', fontSize: '15px' }
+        };
+        const s = sizes[size] || sizes.md;
+
+        this.shadowRoot.innerHTML = `
+      <style>
+        :host {
+          display: inline-block;
+          font-family: 'Inter', system-ui, sans-serif;
+        }
+
+        .badge {
+          display: inline-flex;
+          align-items: center;
+          gap: 5px;
+          padding: ${s.padding};
+          font-size: ${s.fontSize};
+          font-weight: 600;
+          background: ${v.bg};
+          color: ${v.text};
+          border-radius: 100px;
+          white-space: nowrap;
+        }
+
+        .remove-btn {
+          background: none;
+          border: none;
+          cursor: pointer;
+          padding: 0;
+          font-size: 14px;
+          line-height: 1;
+          color: inherit;
+          opacity: 0.7;
+          margin-left: 2px;
+        }
+
+        .remove-btn:hover {
+          opacity: 1;
+        }
+      </style>
+
+      <span class="badge">
+        <slot></slot>
+        ${removable ? '<button class="remove-btn" aria-label="Remove">×</button>' : ''}
+      </span>
+    `;
+    }
+}
+
+registerComponent('af-badge', AfriBadge);
+export default AfriBadge;

package/components/base.d.ts

@@ -0,0 +1,139 @@
+/**
+ * AfriCode Components - Base Class TypeScript Definitions
+ */
+
+/**
+ * Component element creation options
+ */
+export interface ElementOptions {
+  classes?: string[];
+  attributes?: Record<string, string>;
+  text?: string;
+  html?: string;
+  children?: (HTMLElement | string)[];
+}
+
+/**
+ * Custom event detail
+ */
+export interface ComponentEvent<T = any> extends CustomEvent {
+  detail: T;
+}
+
+/**
+ * AfriCode Component Base Class
+ * All AfriCode components extend this class
+ */
+export class AfriCodeComponent extends HTMLElement {
+  /**
+   * Shadow DOM root
+   */
+  shadowRoot: ShadowRoot;
+
+  /**
+   * Component name (e.g., 'af-button')
+   */
+  static readonly is: string;
+
+  /**
+   * Observed attributes that trigger attributeChanged callback
+   */
+  static readonly observedAttributes: string[];
+
+  /**
+   * Create a DOM element with options
+   */
+  createElement(
+    tag: string,
+    options?: ElementOptions
+  ): HTMLElement;
+
+  /**
+   * Emit a custom event
+   */
+  emit<T = any>(name: string, detail?: T): void;
+
+  /**
+   * Load and apply component styles
+   */
+  loadStyles(css?: string): void;
+
+  /**
+   * Render component to shadow DOM
+   */
+  render(): void;
+
+  /**
+   * Mount lifecycle hook
+   */
+  connectedCallback?(): void;
+
+  /**
+   * Unmount lifecycle hook
+   */
+  disconnectedCallback?(): void;
+
+  /**
+   * Attribute change lifecycle hook
+   */
+  attributeChangedCallback?(
+    name: string,
+    oldValue: string | null,
+    newValue: string | null
+  ): void;
+
+  /**
+   * Adopt node into shadow DOM
+   */
+  adoptNode(node: Node): Node;
+
+  /**
+   * Check if attribute exists
+   */
+  hasAttribute(name: string): boolean;
+
+  /**
+   * Get attribute value
+   */
+  getAttribute(name: string): string | null;
+
+  /**
+   * Set attribute value
+   */
+  setAttribute(name: string, value: string): void;
+
+  /**
+   * Remove attribute
+   */
+  removeAttribute(name: string): void;
+
+  /**
+   * Query shadow DOM
+   */
+  querySelector(selector: string): Element | null;
+
+  /**
+   * Query all in shadow DOM
+   */
+  querySelectorAll(selector: string): NodeListOf<Element>;
+}
+
+/**
+ * Component registration
+ */
+export function registerComponent(
+  name: string,
+  component: typeof AfriCodeComponent
+): void;
+
+/**
+ * Component registry
+ */
+export const componentRegistry: Map<string, typeof AfriCodeComponent>;
+
+/**
+ * Get registered component
+ */
+export function getComponent(name: string): typeof AfriCodeComponent | undefined;
+
+export default AfriCodeComponent;

package/components/base.js

@@ -0,0 +1,184 @@
+/**
+ * AfriCode Base Component
+ * 
+ * Abstract base class for all AfriCode Web Components.
+ * Provides common utilities and enforces the Shadow DOM pattern.
+ * 
+ * @module components/base
+ */
+
+import { html } from '../core/html.js';
+
+/**
+ * Base class for AfriCode components
+ * All components extend this to inherit common functionality
+ */
+export class AfriCodeComponent extends HTMLElement {
+    constructor() {
+        super();
+        this.attachShadow({ mode: 'open' });
+        
+        // Native Web Component Error Boundary: intercept child render calls
+        const originalRender = this.render;
+        if (originalRender && typeof originalRender === 'function') {
+            this.render = () => {
+                try {
+                    originalRender.call(this);
+                    this.removeAttribute('has-error');
+                } catch (error) {
+                    console.error(`[AfriCode] Rendering error in <${this.localName}>:`, error);
+                    this.setAttribute('has-error', 'true');
+                    this.shadowRoot.innerHTML = `
+                       <style>
+                         .af-local-error {
+                           padding: 1rem;
+                           border: 1px dashed rgba(220, 20, 60, 0.4);
+                           border-radius: 4px;
+                           color: #DC143C;
+                           font-family: 'Inter', system-ui, sans-serif;
+                           font-size: 0.85rem;
+                           display: flex;
+                           align-items: center;
+                           gap: 8px;
+                           background: rgba(220, 20, 60, 0.05);
+                         }
+                       </style>
+                       <div class="af-local-error">
+                          <span aria-hidden="true">⚠️</span>
+                          <span>Failed to render</span>
+                       </div>
+                    `;
+                    this.emit('af-component-error', { 
+                       component: this.localName, 
+                       message: error.message,
+                       stack: error.stack 
+                    });
+                }
+            };
+        }
+    }
+
+    /**
+     * Component lifecycle - connected to DOM
+     * Empty base implementation to support super calls in subclasses.
+     */
+    connectedCallback() { }
+
+    /**
+     * Load shared Africanity styles into Shadow DOM
+     */
+    // Static cache for Constructable Stylesheets to prevent fetch waterfall
+    static styleCache = new Map();
+
+    /**
+     * Global stylesheets injected by adapters (e.g. Tailwind, custom design systems).
+     * Each entry must be a CSSStyleSheet instance.
+     * Usage: AfriCodeComponent.injectGlobalSheet(sheet)
+     * @type {CSSStyleSheet[]}
+     */
+    static globalSheets = [];
+
+    /**
+     * Inject a global CSSStyleSheet into every AfriCode component's Shadow DOM.
+     * This is the primary integration point for external CSS frameworks like Tailwind.
+     * @param {CSSStyleSheet} sheet - A Constructable Stylesheet instance
+     */
+    static injectGlobalSheet(sheet) {
+        if (!(sheet instanceof CSSStyleSheet)) {
+            console.error('[AfriCode] injectGlobalSheet requires a CSSStyleSheet instance.');
+            return;
+        }
+        if (!AfriCodeComponent.globalSheets.includes(sheet)) {
+            AfriCodeComponent.globalSheets.push(sheet);
+        }
+    }
+
+    /**
+     * Load shared Africanity styles into Shadow DOM.
+     * Optimized to fetch only once per session.
+     * Also adopts any globally injected sheets (e.g. Tailwind utilities).
+     */
+    async loadStyles() {
+        const styleUrl = '/styles/africanity.css';
+
+        // 1. Check cache first
+        if (AfriCodeComponent.styleCache.has(styleUrl)) {
+            this.shadowRoot.adoptedStyleSheets = [
+                AfriCodeComponent.styleCache.get(styleUrl),
+                ...AfriCodeComponent.globalSheets
+            ];
+            return;
+        }
+
+        // 2. Fetch if not cached (Single Request)
+        try {
+            const response = await fetch(styleUrl);
+            const css = await response.text();
+
+            const styleSheet = new CSSStyleSheet();
+            styleSheet.replaceSync(css);
+
+            // Cache it
+            AfriCodeComponent.styleCache.set(styleUrl, styleSheet);
+
+            // Apply core + any global sheets
+            this.shadowRoot.adoptedStyleSheets = [
+                styleSheet,
+                ...AfriCodeComponent.globalSheets
+            ];
+        } catch (err) {
+            console.warn('AfriCode: Failed to load core styles', err);
+        }
+    }
+
+    /**
+     * Get Fibonacci spacing value
+     * @param {number} index - Fibonacci sequence index (1,2,3,5,8,13,21,34,55)
+     * @returns {string} CSS variable reference
+     */
+    spacing(index) {
+        return `var(--space-${index})`;
+    }
+
+    /**
+     * Create element with classes and attributes
+     * @param {string} tag - HTML tag name
+     * @param {Object} options - Element options
+     * @returns {HTMLElement}
+     */
+    createElement(tag, { classes = [], attributes = {}, text = '' } = {}) {
+        const el = document.createElement(tag);
+        if (classes.length) {el.classList.add(...classes);}
+        Object.entries(attributes).forEach(([key, value]) => el.setAttribute(key, value));
+        if (text) {el.textContent = text;}
+        return el;
+    }
+
+
+    /**
+     * Emit a custom event
+     * @param {string} name - Event name
+     * @param {*} detail - Event detail data
+     */
+    emit(name, detail) {
+        this.dispatchEvent(new CustomEvent(name, {
+            detail,
+            bubbles: true,
+            composed: true
+        }));
+    }
+}
+
+/**
+ * Register a component with the Custom Elements registry
+ * @param {string} name - Component tag name (must include hyphen)
+ * @param {typeof HTMLElement} component - Component class
+ */
+export function registerComponent(name, component) {
+    if (!customElements.get(name)) {
+        customElements.define(name, component);
+    }
+}
+
+export { html };
+export default { AfriCodeComponent, registerComponent, html };

package/components/button.js

@@ -0,0 +1,164 @@
+/**
+ * AfriCode Button Component
+ * 
+ * Versatile button with multiple variants, sizes, and cultural themes.
+ * Suitable for: E-commerce, Healthcare, Education, Finance, Government
+ * 
+ * @module components/button
+ */
+
+import { AfriCodeComponent, registerComponent } from './base.js';
+
+export class AfriButton extends AfriCodeComponent {
+    static get observedAttributes() {
+        return ['variant', 'size', 'theme', 'disabled', 'loading', 'icon', 'aria-label'];
+    }
+
+    constructor() {
+        super();
+        this.render();
+    }
+
+    connectedCallback() {
+        const button = this.shadowRoot.querySelector('button');
+        button?.addEventListener('click', (e) => {
+            if (this.hasAttribute('disabled') || this.hasAttribute('loading')) {
+                e.preventDefault();
+                return;
+            }
+            this.emit('af-click', { originalEvent: e });
+        });
+    }
+
+    attributeChangedCallback() {
+        this.render();
+    }
+
+    render() {
+        const variant = this.getAttribute('variant') || 'primary';
+        const size = this.getAttribute('size') || 'md';
+        const theme = this.getAttribute('theme') || 'tanzania';
+        const isDisabled = this.hasAttribute('disabled');
+        const isLoading = this.hasAttribute('loading');
+        const icon = this.getAttribute('icon');
+        const ariaLabel = this.getAttribute('aria-label');
+
+        const themes = {
+            tanzania: { primary: '#1EB53A', accent: '#FCD116', text: '#FFFFFF' },
+            maasai: { primary: '#FF0000', accent: '#8B0000', text: '#FFFFFF' },
+            ndebele: { primary: '#4169E1', accent: '#FFD700', text: '#FFFFFF' },
+            ocean: { primary: '#00A3DD', accent: '#0077BE', text: '#FFFFFF' }
+        };
+
+        const t = themes[theme] || themes.tanzania;
+
+        this.shadowRoot.innerHTML = `
+      <style>
+        :host {
+          display: inline-block;
+        }
+
+        button {
+          font-family: 'Inter', system-ui, sans-serif;
+          font-weight: 600;
+          border: none;
+          border-radius: 5px;
+          cursor: pointer;
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          gap: 8px;
+          transition: all 200ms ease-out;
+          position: relative;
+          overflow: hidden;
+        }
+
+        /* Sizes */
+        .size-sm { padding: 5px 13px; font-size: 13px; }
+        .size-md { padding: 8px 21px; font-size: 15px; }
+        .size-lg { padding: 13px 34px; font-size: 17px; }
+
+        /* Variants */
+        .variant-primary {
+          background: ${t.primary};
+          color: ${t.text};
+        }
+        .variant-primary:hover:not(:disabled) {
+          filter: brightness(1.1);
+          transform: translateY(-2px);
+          box-shadow: 0 4px 12px rgba(0,0,0,0.2);
+        }
+
+        .variant-secondary {
+          background: transparent;
+          color: ${t.primary};
+          border: 2px solid ${t.primary};
+        }
+        .variant-secondary:hover:not(:disabled) {
+          background: ${t.primary};
+          color: ${t.text};
+        }
+
+        .variant-ghost {
+          background: transparent;
+          color: ${t.primary};
+        }
+        .variant-ghost:hover:not(:disabled) {
+          background: rgba(0,0,0,0.05);
+        }
+
+        .variant-gradient {
+          background: linear-gradient(135deg, ${t.primary} 0%, ${t.accent} 100%);
+          color: ${t.text};
+        }
+        .variant-gradient:hover:not(:disabled) {
+          transform: translateY(-2px);
+          box-shadow: 0 6px 20px rgba(0,0,0,0.25);
+        }
+
+        /* States */
+        button:disabled {
+          opacity: 0.5;
+          cursor: not-allowed;
+        }
+
+        button:active:not(:disabled) {
+          transform: translateY(0);
+        }
+
+        /* Loading spinner */
+        .spinner {
+          width: 16px;
+          height: 16px;
+          border: 2px solid transparent;
+          border-top-color: currentColor;
+          border-radius: 50%;
+          animation: spin 0.8s linear infinite;
+        }
+
+        @keyframes spin {
+          to { transform: rotate(360deg); }
+        }
+
+        /* Icon */
+        .icon {
+          font-size: 1.1em;
+        }
+      </style>
+
+      <button 
+        class="variant-${variant} size-${size}"
+        ${isDisabled ? 'disabled' : ''}
+        ${ariaLabel ? `aria-label="${ariaLabel}"` : ''}
+        ${isLoading ? 'aria-busy="true"' : ''}
+      >
+        ${isLoading ? '<span class="spinner"></span>' : ''}
+        ${icon && !isLoading ? `<span class="icon">${icon}</span>` : ''}
+        <slot></slot>
+      </button>
+    `;
+    }
+}
+
+registerComponent('af-button', AfriButton);
+export default AfriButton;