@africode/core 5.0.0

package/components/error-boundary.js

@@ -0,0 +1,155 @@
+import { AfriCodeComponent, registerComponent } from './base.js';
+
+/**
+ * AfriCode Error Boundary Component
+ * 
+ * Native Web Component implementation of an error boundary.
+ * Listens for 'af-component-error' events bubbling up from children.
+ * Gracefully displays a localized fallback UI.
+ * 
+ * @module components/error-boundary
+ */
+export class AfriErrorBoundary extends AfriCodeComponent {
+    static get observedAttributes() {
+        return ['theme', 'fallback-message'];
+    }
+
+    constructor() {
+        super();
+        this._hasError = false;
+        this._errorDetail = null;
+        this.render();
+    }
+
+    connectedCallback() {
+        // Listen for internal errors bubbling up from custom AfriCode children
+        this.addEventListener('af-component-error', this._handleError.bind(this));
+    }
+
+    disconnectedCallback() {
+        this.removeEventListener('af-component-error', this._handleError.bind(this));
+    }
+
+    _handleError(e) {
+        // Prevent it from bubbling further up and crashing higher boundaries
+        e.stopPropagation();
+        
+        this._hasError = true;
+        this._errorDetail = e.detail;
+        
+        console.warn('[AfriCode Boundary] Caught error:', this._errorDetail);
+        this.render();
+    }
+
+    reset() {
+        this._hasError = false;
+        this._errorDetail = null;
+        this.render();
+    }
+
+    attributeChangedCallback() {
+        this.render();
+    }
+
+    render() {
+        const theme = this.getAttribute('theme') || 'tanzania';
+        const fallbackMessage = this.getAttribute('fallback-message') || 'A part of this page failed to load.';
+
+        // Use appropriate semantic warning colors depending on culture theme
+        const themes = {
+            tanzania: { bg: '#FFF9E6', border: '#FCD116', text: '#5A4A00' },
+            maasai: { bg: '#FFEEEE', border: '#FF0000', text: '#8B0000' },
+            ndebele: { bg: '#EBF0FF', border: '#4169E1', text: '#002B5C' },
+            ocean: { bg: '#E6FAFF', border: '#00A3DD', text: '#004A66' }
+        };
+
+        const t = themes[theme] || themes.tanzania;
+
+        if (this._hasError) {
+            this.shadowRoot.innerHTML = `
+                <style>
+                    :host { display: block; width: 100%; font-family: 'Inter', system-ui, sans-serif; }
+                    .boundary-error {
+                        background: ${t.bg};
+                        border-left: 4px solid ${t.border};
+                        color: ${t.text};
+                        padding: 16px 20px;
+                        border-radius: 4px;
+                        margin: 12px 0;
+                        box-shadow: 0 2px 8px rgba(0,0,0,0.05);
+                    }
+                    .boundary-header {
+                        display: flex;
+                        align-items: center;
+                        gap: 12px;
+                        font-weight: 600;
+                        margin-bottom: 8px;
+                        font-size: 16px;
+                    }
+                    .boundary-message {
+                        font-size: 14px;
+                        opacity: 0.9;
+                        margin-bottom: 12px;
+                    }
+                    .boundary-dev-detail {
+                        font-family: monospace;
+                        font-size: 12px;
+                        background: rgba(0,0,0,0.05);
+                        padding: 8px;
+                        border-radius: 4px;
+                        overflow-x: auto;
+                        white-space: pre-wrap;
+                    }
+                    .boundary-action {
+                        margin-top: 12px;
+                    }
+                    button {
+                        background: transparent;
+                        border: 1px solid ${t.border};
+                        color: ${t.text};
+                        padding: 6px 12px;
+                        border-radius: 4px;
+                        cursor: pointer;
+                        font-weight: 500;
+                        transition: background 0.2s;
+                    }
+                    button:hover {
+                        background: rgba(0,0,0,0.05);
+                    }
+                </style>
+                <div class="boundary-error" role="alert">
+                    <div class="boundary-header">
+                        <span aria-hidden="true">🔄</span>
+                        <span>Component Recovery</span>
+                    </div>
+                    <div class="boundary-message">${fallbackMessage}</div>
+                    
+                    ${this._errorDetail ? `
+                    <div class="boundary-dev-detail">
+                        <code>&lt;${this._errorDetail.component}&gt;: ${this._errorDetail.message}</code>
+                    </div>
+                    ` : ''}
+
+                    <div class="boundary-action">
+                        <button id="retry-btn">Try Again</button>
+                    </div>
+                </div>
+            `;
+            
+            // Re-bind retry logic
+            this.shadowRoot.getElementById('retry-btn').addEventListener('click', () => {
+                this.reset();
+            });
+            return;
+        }
+
+        // If no error, just passthrough the light DOM via slots
+        this.shadowRoot.innerHTML = `
+            <style>:host { display: block; }</style>
+            <slot></slot>
+        `;
+    }
+}
+
+registerComponent('af-error-boundary', AfriErrorBoundary);
+export default AfriErrorBoundary;

package/components/form.js

@@ -0,0 +1,131 @@
+import { AfriCodeComponent, registerComponent } from './base.js';
+import { Validation, schemas } from '../core/validation.js';
+
+/**
+ * Smart Form Component
+ * Handles submission, loading state, and validation.
+ * 
+ * Usage:
+ * <af-form action="/api/login" method="POST">
+ *   <af-input name="email"></af-input>
+ * </af-form>
+ */
+export class AfriForm extends AfriCodeComponent {
+    static get observedAttributes() { return ['action', 'method', 'error', 'success', 'schema']; }
+
+    constructor() {
+        super();
+        this.handleSubmit = this.handleSubmit.bind(this);
+    }
+
+    connectedCallback() {
+        this.render();
+        this.shadowRoot.querySelector('form').addEventListener('submit', this.handleSubmit);
+        this.loadStyles();
+    }
+
+    async handleSubmit(e) {
+        e.preventDefault();
+        const form = e.target;
+        const submitBtn = this.querySelector('[type="submit"]') || this.shadowRoot.querySelector('button[type="submit"]');
+
+        // Get validation schema
+        const schemaName = this.getAttribute('schema');
+        const schema = schemaName ? this._getSchema(schemaName) : null;
+
+        // derived from attributes
+        const action = this.getAttribute('action');
+        const method = this.getAttribute('method') || 'GET';
+
+        // Collect form data from native controls
+        const formData = new FormData(form);
+        const data = Object.fromEntries(formData.entries());
+
+        // Include custom af-input values that live in shadow DOM
+        Array.from(this.querySelectorAll('af-input')).forEach((customInput) => {
+            const name = customInput.getAttribute('name');
+            if (name) {
+                data[name] = customInput.value;
+            }
+        });
+
+        // Validate if schema provided
+        if (schema) {
+            const validationResult = Validation.validate(schema, data);
+            if (!validationResult.success) {
+                this._showValidationErrors(validationResult.errors);
+                this.emit('af-validation-error', { errors: validationResult.errors });
+                return;
+            }
+        }
+
+        if (!action) {return;}
+
+        // Loading State
+        if (submitBtn) {
+            var originalText = submitBtn.textContent;
+            submitBtn.textContent = 'Wait...';
+            submitBtn.disabled = true;
+        }
+
+        try {
+            const response = await fetch(action, {
+                method: method,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(data)
+            });
+
+            if (response.ok) {
+                this.emit('success', await response.json());
+                this.setAttribute('success', 'Form submitted successfully!');
+                this.removeAttribute('error');
+            } else {
+                const errorData = await response.text();
+                this.emit('error', errorData);
+                this.setAttribute('error', errorData);
+                this.removeAttribute('success');
+            }
+        } catch (err) {
+            this.emit('error', err.message);
+            this.setAttribute('error', err.message);
+            this.removeAttribute('success');
+        } finally {
+            if (submitBtn) {
+                submitBtn.textContent = originalText;
+                submitBtn.disabled = false;
+            }
+        }
+    }
+
+    _getSchema(schemaName) {
+        return schemas[schemaName] || null;
+    }
+
+    _showValidationErrors(errors) {
+        // Clear previous errors
+        this.shadowRoot.querySelectorAll('.field-error').forEach(el => el.remove());
+
+        // Show errors on corresponding inputs
+        Object.entries(errors).forEach(([fieldName, errorMessage]) => {
+            const input = this.querySelector(`[name="${fieldName}"]`);
+            if (input) {
+                // For custom af-input components
+                if (input.tagName === 'AF-INPUT') {
+                    input.setAttribute('error', errorMessage);
+                } else {
+                    // For regular inputs, add error display
+                    const errorDiv = document.createElement('div');
+                    errorDiv.className = 'field-error';
+                    errorDiv.textContent = errorMessage;
+                    errorDiv.style.color = 'red';
+                    errorDiv.style.fontSize = '12px';
+                    errorDiv.style.marginTop = '4px';
+                    input.parentNode.insertBefore(errorDiv, input.nextSibling);
+                }
+            }
+        });
+    }
+}
+
+registerComponent('af-form', AfriForm);
+export default AfriForm;

package/components/grid.js

@@ -0,0 +1,273 @@
+/**
+ * AfriCode Grid Layout — <af-grid>
+ *
+ * A fully-featured, reactive responsive grid system.
+ *
+ * Attributes:
+ *   min-width    — Minimum column width before wrapping (default: 280px)
+ *   gap          — Grid gap spacing (default: 24px)
+ *   columns      — Fixed column count (overrides auto-fit / min-width)
+ *   rows         — Fixed row count for explicit grid
+ *   layout       — Preset layouts: 'auto' | 'masonry' | 'sidebar' | 'holy-grail' | 'bento'
+ *   align        — Align items: 'start' | 'center' | 'end' | 'stretch' (default: stretch)
+ *   justify      — Justify items: 'start' | 'center' | 'end' | 'stretch' (default: stretch)
+ *   dense        — Enable grid-auto-flow: dense (boolean attribute)
+ *   sidebar-side — 'left' | 'right' for sidebar layout (default: left)
+ *   sidebar-width — Width of the sidebar column (default: 280px)
+ *
+ * Events:
+ *   af-grid-resize — Fired when grid reflows due to container resize
+ *
+ * Examples:
+ *   <af-grid min-width="300px" gap="32px">...</af-grid>
+ *   <af-grid columns="3" gap="16px">...</af-grid>
+ *   <af-grid layout="sidebar" sidebar-width="240px">...</af-grid>
+ *   <af-grid layout="bento" gap="16px">...</af-grid>
+ */
+import { AfriCodeComponent, registerComponent, html } from './base.js';
+
+// Preset layout generators
+function getLayoutTemplate(layout, attrs) {
+  const {
+    sidebarSide = 'left',
+    sidebarWidth = '280px',
+    minWidth = '280px',
+    gap = '24px',
+    columns,
+    rows,
+    align = 'stretch',
+    justify = 'stretch',
+    dense = false,
+  } = attrs;
+
+  const denseVal = dense ? 'dense' : '';
+  const base = `
+        align-items: ${align};
+        justify-items: ${justify};
+        gap: ${gap};
+    `;
+
+  switch (layout) {
+    case 'sidebar':
+      return sidebarSide === 'right'
+        ? `display: grid; grid-template-columns: 1fr ${sidebarWidth}; ${base}`
+        : `display: grid; grid-template-columns: ${sidebarWidth} 1fr; ${base}`;
+
+    case 'holy-grail':
+      return `
+                display: grid;
+                grid-template-columns: ${sidebarWidth} 1fr ${sidebarWidth};
+                grid-template-rows: auto 1fr auto;
+                ${base}
+            `;
+
+    case 'bento':
+      // Bento grid: 12-column base, children use grid-column/row spans
+      return `
+                display: grid;
+                grid-template-columns: repeat(12, 1fr);
+                grid-auto-rows: minmax(120px, auto);
+                grid-auto-flow: row ${denseVal};
+                ${base}
+            `;
+
+    case 'masonry':
+      // CSS-native masonry (progressive enhancement)
+      return `
+                display: grid;
+                grid-template-columns: repeat(auto-fill, minmax(${minWidth}, 1fr));
+                grid-template-rows: masonry;
+                grid-auto-flow: row ${denseVal};
+                ${base}
+            `;
+
+    case 'auto':
+    default: {
+      const colValue = columns
+        ? `repeat(${columns}, 1fr)`
+        : `repeat(auto-fit, minmax(${minWidth}, 1fr))`;
+      const rowValue = rows ? `repeat(${rows}, 1fr)` : 'auto';
+      return `
+                display: grid;
+                grid-template-columns: ${colValue};
+                ${rows ? `grid-template-rows: ${rowValue};` : ''}
+                grid-auto-flow: row ${denseVal};
+                ${base}
+            `;
+    }
+  }
+}
+
+export class AfriGrid extends AfriCodeComponent {
+  static get observedAttributes() {
+    return [
+      'min-width',
+      'gap',
+      'columns',
+      'rows',
+      'layout',
+      'align',
+      'justify',
+      'dense',
+      'sidebar-side',
+      'sidebar-width',
+    ];
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) {
+      this.render();
+    }
+  }
+
+  _getAttrs() {
+    return {
+      minWidth: this.getAttribute('min-width') || '280px',
+      gap: this.getAttribute('gap') || '24px',
+      columns: this.getAttribute('columns') || null,
+      rows: this.getAttribute('rows') || null,
+      layout: this.getAttribute('layout') || 'auto',
+      align: this.getAttribute('align') || 'stretch',
+      justify: this.getAttribute('justify') || 'stretch',
+      dense: this.hasAttribute('dense'),
+      sidebarSide: this.getAttribute('sidebar-side') || 'left',
+      sidebarWidth: this.getAttribute('sidebar-width') || '280px',
+    };
+  }
+
+  _buildResponsiveBreakpoints(attrs) {
+    // Only apply responsive fallback to auto/masonry layouts
+    if (attrs.layout !== 'auto' && attrs.layout !== 'masonry') {
+      return '';
+    }
+
+    return `
+            @media (max-width: 768px) {
+                .grid {
+                    grid-template-columns: repeat(auto-fit, minmax(min(${attrs.minWidth}, 100%), 1fr));
+                }
+            }
+            @media (max-width: 480px) {
+                .grid {
+                    grid-template-columns: 1fr;
+                }
+            }
+        `;
+  }
+
+  _buildSidebarResponsive(attrs) {
+    if (attrs.layout !== 'sidebar' && attrs.layout !== 'holy-grail') {
+      return '';
+    }
+    return `
+            @media (max-width: 768px) {
+                .grid {
+                    grid-template-columns: 1fr;
+                }
+            }
+        `;
+  }
+
+  render() {
+    const attrs = this._getAttrs();
+    const gridStyles = getLayoutTemplate(attrs.layout, attrs);
+    const responsiveStyles =
+      this._buildResponsiveBreakpoints(attrs) + this._buildSidebarResponsive(attrs);
+
+    this.shadowRoot.innerHTML = html`
+      <style>
+        :host {
+            display: block;
+            width: 100%;
+            box-sizing: border-box;
+        }
+
+        .grid {
+            ${gridStyles}
+            width: 100%;
+            box-sizing: border-box;
+        }
+
+        /* Slotted children base styles */
+        ::slotted(*) {
+            min-width: 0; /* Prevent overflow in grid context */
+        }
+
+        ${responsiveStyles}
+      </style>
+
+      <div
+        class="grid"
+        role="list"
+        part="grid"
+        aria-label="${this.getAttribute('aria-label') || 'Grid layout'}"
+      >
+        <slot></slot>
+      </div>
+    `;
+  }
+
+  connectedCallback() {
+    this.render();
+    this._setupResizeObserver();
+  }
+
+  disconnectedCallback() {
+    if (this._resizeObserver) {
+      this._resizeObserver.disconnect();
+    }
+  }
+
+  _setupResizeObserver() {
+    if (typeof ResizeObserver === 'undefined') {
+      return;
+    }
+
+    let lastWidth = this.offsetWidth;
+    this._resizeObserver = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const newWidth = entry.contentRect.width;
+        if (Math.abs(newWidth - lastWidth) > 10) {
+          lastWidth = newWidth;
+          this.emit('af-grid-resize', {
+            width: newWidth,
+            height: entry.contentRect.height,
+            layout: this.getAttribute('layout') || 'auto',
+          });
+        }
+      }
+    });
+
+    this._resizeObserver.observe(this);
+  }
+
+  /**
+   * Public API: programmatically update grid layout
+   * @param {string} layout - New layout preset
+   */
+  setLayout(layout) {
+    this.setAttribute('layout', layout);
+  }
+
+  /**
+   * Public API: programmatically set column count
+   * @param {number} count - Number of columns
+   */
+  setColumns(count) {
+    this.setAttribute('columns', String(count));
+  }
+
+  /**
+   * Public API: toggle dense packing
+   * @param {boolean} enabled
+   */
+  setDense(enabled) {
+    if (enabled) {
+      this.setAttribute('dense', '');
+    } else {
+      this.removeAttribute('dense');
+    }
+  }
+}
+
+registerComponent('af-grid', AfriGrid);

package/components/hero.js

@@ -0,0 +1,138 @@
+import { AfriCodeComponent, registerComponent } from './base.js';
+import { html } from '../core/html.js';
+import { store } from '../core/store.js';
+import { subscribe } from '../core/state.js';
+
+/**
+ * AfriHero Component
+ * 
+ * High-impact hero section with support for patterns and rhythmic layout.
+ * 
+ * @example
+ * <af-hero 
+ *   title="AfriCode" 
+ *   subtitle="The Rhythmic Web Framework" 
+ *   pattern="kente">
+ * </af-hero>
+ */
+export class AfriHero extends AfriCodeComponent {
+    static get observedAttributes() { return ['title', 'subtitle', 'pattern', 'overlay']; }
+
+    connectedCallback() {
+        super.connectedCallback();
+        this.render();
+        this.loadStyles();
+    }
+
+    render() {
+        const title = this.getAttribute('title') || 'AfriCode';
+        const subtitle = this.getAttribute('subtitle') || '';
+        const pattern = this.getAttribute('pattern') || '';
+        const variant = this.getAttribute('variant') || 'default';
+
+        this.shadowRoot.innerHTML = `
+            <style>
+                :host {
+                    display: flex;
+                    flex-direction: column;
+                    align-items: center;
+                    justify-content: center;
+                    text-align: center;
+                    padding: 120px 5%;
+                    min-height: 60vh;
+                    background: var(--bg-base, #020617);
+                    color: var(--text-main, white);
+                    position: relative;
+                    overflow: hidden;
+                }
+
+                .content {
+                    position: relative;
+                    z-index: 10;
+                    max-width: 900px;
+                    opacity: 0;
+                    transform: translateY(20px);
+                    animation: fadeInUp 0.8s cubic-bezier(0.16, 1, 0.3, 1) forwards;
+                }
+
+                @keyframes fadeInUp {
+                    to { opacity: 1; transform: translateY(0); }
+                }
+
+                h1 {
+                    font-family: 'Outfit', 'Space Grotesk', sans-serif;
+                    font-size: clamp(3rem, 8vw, 5rem);
+                    font-weight: 900;
+                    line-height: 1.1;
+                    margin-bottom: 24px;
+                    letter-spacing: -0.04em;
+                    background: linear-gradient(135deg, var(--text-main, #fff) 30%, var(--text-muted, rgba(255,255,255,0.5)) 100%);
+                    -webkit-background-clip: text;
+                    -webkit-text-fill-color: transparent;
+                }
+
+                p {
+                    font-family: 'Inter', sans-serif;
+                    font-size: clamp(1.1rem, 2vw, 1.5rem);
+                    color: var(--text-secondary, #94a3b8);
+                    line-height: 1.5;
+                    margin-bottom: 40px;
+                    max-width: 700px;
+                    margin-left: auto;
+                    margin-right: auto;
+                }
+
+                /* Visual Accents */
+                .aura {
+                    position: absolute;
+                    inset: 0;
+                    background: radial-gradient(circle at 50% -20%, rgba(30,181,58,0.15), transparent 70%);
+                    z-index: 1;
+                }
+
+                .mesh {
+                    position: absolute;
+                    inset: 0;
+                    background-image: radial-gradient(rgba(255,255,255,0.03) 1px, transparent 1px);
+                    background-size: 40px 40px;
+                    z-index: 2;
+                }
+
+                ${pattern ? `
+                .pattern-bg {
+                    position: absolute;
+                    inset: 0;
+                    background-image: url('${pattern}');
+                    background-size: cover;
+                    background-position: center;
+                    opacity: 0.15;
+                    z-index: 1;
+                }
+                ` : ''}
+
+                ::slotted([slot="actions"]) {
+                    display: flex;
+                    gap: 16px;
+                    justify-content: center;
+                    flex-wrap: wrap;
+                }
+            </style>
+            
+            <div class="aura"></div>
+            <div class="mesh"></div>
+            ${pattern ? `<div class="pattern-bg"></div>` : ''}
+            
+            <div class="content">
+                <h1>${title}</h1>
+                ${subtitle ? `<p>${subtitle}</p>` : ''}
+                <div class="actions">
+                    <slot name="actions"></slot>
+                </div>
+                <slot></slot>
+            </div>
+        `;
+    }
+}
+
+registerComponent('af-hero', AfriHero);
+export default AfriHero;