@africode/core 5.0.4 → 5.0.5

package/README.md

@@ -43,6 +43,7 @@ Following the rollout framework, AfriCode v5.0.0 implements a phased Pan-African
 - **33+ Web Components**: African-themed UI elements with cultural semiotics
 - **Procedural SVG Engine**: Fractal geometry for traditional patterns
 - **Mobile-First Design**: Optimized for African connectivity constraints
+- **Native UI Kit**: Shadcn-style Web Components like `af-ui-button`, `af-ui-card`, and `af-ui-input` for consistent app UI
 
 ## 🚀 Quick Start
 
@@ -342,6 +343,35 @@ Then use them in your HTML:
 <af-button onclick="handleClick()">Click Me</af-button>
 ```
 
+### Native AfriCode UI Kit
+
+AfriCode now includes a native UI kit with shadcn-inspired Web Components for rapid interface design. The Tailwind starter demonstrates the new UI kit using components like `af-ui-button`, `af-ui-card`, `af-ui-input`, `af-ui-badge`, and `af-ui-switch` in a Shadow DOM-friendly workflow.
+
+The library is optimized for consistent spacing, elevation, and interactive states across theme-aware apps.
+
+Use the Tailwind starter template for a ready-made UI experience:
+
+```bash
+create-africode my-app --template starter-tailwind
+cd my-app
+bun install
+bun run dev
+```
+
+Example usage:
+
+```html
+<af-ui-card variant="outlined" clickable>
+  <h3>Actionable Panel</h3>
+  <p>Build data-driven experiences with native AfriCode UI components.</p>
+  <af-ui-badge variant="success" pill>Ready</af-ui-badge>
+</af-ui-card>
+
+<af-ui-input label="Email" placeholder="you@example.com"></af-ui-input>
+<af-ui-switch checked></af-ui-switch>
+<af-ui-button variant="primary">Submit</af-ui-button>
+```
+
 ## ⚙️ Development
 
 ### Hot Module Replacement (HMR)

package/components/index.js

@@ -8,6 +8,13 @@
 export { AfriCodeComponent } from './base.js';
 export { AfriErrorBoundary } from './error-boundary.js';
 
+// UI Kit Components
+export { AfriUIButton } from './ui-button.js';
+export { AfriUICard } from './ui-card.js';
+export { AfriUIInput } from './ui-input.js';
+export { AfriUIBadge } from './ui-badge.js';
+export { AfriUISwitch } from './ui-switch.js';
+
 // Map of Tag Name -> Dynamic Import
 export const componentMap = {
     // Core UI
@@ -20,6 +27,13 @@ export const componentMap = {
     'af-section': () => import('./section.js'),
     'af-icon': () => import('./icon.js'),
 
+    // AfriCode UI Kit
+    'af-ui-button': () => import('./ui-button.js'),
+    'af-ui-card': () => import('./ui-card.js'),
+    'af-ui-input': () => import('./ui-input.js'),
+    'af-ui-badge': () => import('./ui-badge.js'),
+    'af-ui-switch': () => import('./ui-switch.js'),
+
     // Enterprise
     'af-accordion': () => import('./accordion.js'),
     'af-hero': () => import('./hero.js'),

package/components/ui-badge.js

@@ -0,0 +1,61 @@
+/**
+ * AfriCode UI Badge
+ *
+ * A minimal badge component for status labels and counters.
+ * @module components/ui-badge
+ */
+
+import { AfriCodeComponent, registerComponent, html } from './base.js';
+
+export class AfriUIBadge extends AfriCodeComponent {
+  static get observedAttributes() {
+    return ['variant', 'size', 'pill'];
+  }
+
+  constructor() {
+    super();
+    this.render();
+  }
+
+  attributeChangedCallback() {
+    this.render();
+  }
+
+  render() {
+    const variant = this.getAttribute('variant') || 'secondary';
+    const size = this.getAttribute('size') || 'md';
+    const pill = this.hasAttribute('pill');
+
+    this.shadowRoot.innerHTML = html`
+      <style>
+        :host { display: inline-block; font-family: 'Inter', system-ui, sans-serif; }
+
+        .badge {
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          gap: 0.4rem;
+          border-radius: ${pill ? '999px' : '0.6rem'};
+          padding: ${size === 'sm' ? '0.25rem 0.65rem' : size === 'lg' ? '0.55rem 1rem' : '0.4rem 0.8rem'};
+          font-size: ${size === 'sm' ? '0.75rem' : size === 'lg' ? '0.95rem' : '0.85rem'};
+          font-weight: 700;
+          color: #111827;
+          background: var(--af-ui-badge-bg, #e2e8f0);
+          border: 1px solid transparent;
+          white-space: nowrap;
+        }
+
+        .badge.primary { background: #2563eb; color: #ffffff; }
+        .badge.success { background: #16a34a; color: #ffffff; }
+        .badge.warning { background: #f59e0b; color: #0f172a; }
+        .badge.danger { background: #dc2626; color: #ffffff; }
+        .badge.secondary { background: #f8fafc; color: #0f172a; }
+      </style>
+
+      <span class="badge ${variant}"><slot></slot></span>
+    `;
+  }
+}
+
+registerComponent('af-ui-badge', AfriUIBadge);
+export default AfriUIBadge;

package/components/ui-button.js

@@ -0,0 +1,149 @@
+/**
+ * AfriCode UI Button
+ *
+ * A shadcn-style button component with variant and size options.
+ * Works well with Tailwind-style theming and Shadow DOM.
+ *
+ * @module components/ui-button
+ */
+
+import { AfriCodeComponent, registerComponent, html } from './base.js';
+
+export class AfriUIButton extends AfriCodeComponent {
+  static get observedAttributes() {
+    return ['variant', 'size', 'disabled', 'loading', 'full-width', 'aria-label'];
+  }
+
+  constructor() {
+    super();
+    this.render();
+  }
+
+  connectedCallback() {
+    const button = this.shadowRoot.querySelector('button');
+    button?.addEventListener('click', (event) => {
+      if (this.hasAttribute('disabled') || this.hasAttribute('loading')) {
+        event.preventDefault();
+        return;
+      }
+      this.emit('af-ui-button-click', { originalEvent: event });
+    });
+  }
+
+  attributeChangedCallback() {
+    this.render();
+  }
+
+  render() {
+    const variant = this.getAttribute('variant') || 'primary';
+    const size = this.getAttribute('size') || 'md';
+    const isDisabled = this.hasAttribute('disabled');
+    const isLoading = this.hasAttribute('loading');
+    const ariaLabel = this.getAttribute('aria-label') || '';
+
+    this.shadowRoot.innerHTML = html`
+      <style>
+        :host { display: inline-block; }
+
+        button {
+          all: unset;
+          box-sizing: border-box;
+          min-height: 42px;
+          padding: 0 18px;
+          border-radius: 999px;
+          font-family: 'Inter', system-ui, sans-serif;
+          font-weight: 600;
+          cursor: pointer;
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          gap: 0.5rem;
+          transition: transform 180ms ease, box-shadow 180ms ease, background-color 180ms ease;
+          text-decoration: none;
+          border: 1px solid transparent;
+          user-select: none;
+          white-space: nowrap;
+        }
+
+        :host([full-width]) button { width: 100%; }
+
+        button.primary {
+          background: #2563eb;
+          color: #fff;
+          box-shadow: 0 8px 24px rgba(37, 99, 235, 0.24);
+        }
+
+        button.primary:hover:not(:disabled) {
+          transform: translateY(-1px);
+          background: #1d4ed8;
+        }
+
+        button.secondary {
+          background: #f8fafc;
+          color: #1f2937;
+          border-color: #cbd5e1;
+        }
+
+        button.secondary:hover:not(:disabled) {
+          background: #e2e8f0;
+        }
+
+        button.ghost {
+          background: transparent;
+          color: #0f172a;
+        }
+
+        button.ghost:hover:not(:disabled) {
+          background: rgba(15, 23, 42, 0.05);
+        }
+
+        button.link {
+          background: transparent;
+          color: #2563eb;
+          box-shadow: none;
+          padding: 0;
+          border-radius: 0;
+        }
+
+        button.link:hover:not(:disabled) {
+          text-decoration: underline;
+        }
+
+        button.size-sm { min-height: 34px; padding: 0 14px; font-size: 0.85rem; }
+        button.size-md { min-height: 42px; padding: 0 18px; font-size: 0.95rem; }
+        button.size-lg { min-height: 50px; padding: 0 22px; font-size: 1rem; }
+
+        button:disabled {
+          opacity: 0.55;
+          cursor: not-allowed;
+          transform: none;
+          box-shadow: none;
+        }
+
+        .spinner {
+          width: 18px;
+          height: 18px;
+          border: 2px solid currentColor;
+          border-bottom-color: transparent;
+          border-radius: 999px;
+          animation: spin 0.8s linear infinite;
+        }
+
+        @keyframes spin { to { transform: rotate(360deg); } }
+      </style>
+
+      <button
+        class="${variant} ${size}"
+        ${isDisabled ? 'disabled' : ''}
+        ${ariaLabel ? `aria-label="${ariaLabel}"` : ''}
+        ${isLoading ? 'aria-busy="true"' : ''}
+      >
+        ${isLoading ? html`<span class="spinner"></span>` : ''}
+        <slot></slot>
+      </button>
+    `;
+  }
+}
+
+registerComponent('af-ui-button', AfriUIButton);
+export default AfriUIButton;

package/components/ui-card.js

@@ -0,0 +1,75 @@
+/**
+ * AfriCode UI Card
+ *
+ * A lightweight card component for content grouping.
+ * Provides subtle elevation and variant support.
+ *
+ * @module components/ui-card
+ */
+
+import { AfriCodeComponent, registerComponent, html } from './base.js';
+
+export class AfriUICard extends AfriCodeComponent {
+  static get observedAttributes() {
+    return ['variant', 'bordered', 'clickable'];
+  }
+
+  constructor() {
+    super();
+    this.render();
+  }
+
+  connectedCallback() {
+    this.loadStyles();
+    if (this.hasAttribute('clickable')) {
+      this.shadowRoot.querySelector('.card')?.addEventListener('click', () => {
+        this.emit('af-ui-card-click');
+      });
+    }
+  }
+
+  attributeChangedCallback() {
+    this.render();
+  }
+
+  render() {
+    const variant = this.getAttribute('variant') || 'elevated';
+    const bordered = this.hasAttribute('bordered');
+    const clickable = this.hasAttribute('clickable');
+
+    this.shadowRoot.innerHTML = html`
+      <style>
+        :host { display: block; }
+
+        .card {
+          border-radius: 1rem;
+          padding: 1.5rem;
+          background: #ffffff;
+          color: #0f172a;
+          transition: transform 180ms ease, box-shadow 180ms ease, border-color 180ms ease;
+          border: 1px solid transparent;
+          box-shadow: 0 16px 32px rgba(15, 23, 42, 0.08);
+        }
+
+        .card.elevated { background: #fff; }
+        .card.flat { background: #f8fafc; box-shadow: none; }
+        .card.outlined { background: #fff; border-color: #e2e8f0; box-shadow: none; }
+
+        .card:hover:not(.disabled) {
+          transform: translateY(-2px);
+        }
+
+        :host([bordered]) .card { border-color: #cbd5e1; }
+
+        :host([clickable]) .card { cursor: pointer; }
+      </style>
+
+      <article class="card ${variant}">
+        <slot></slot>
+      </article>
+    `;
+  }
+}
+
+registerComponent('af-ui-card', AfriUICard);
+export default AfriUICard;

package/components/ui-input.js

@@ -0,0 +1,110 @@
+/**
+ * AfriCode UI Input
+ *
+ * A styled input component with label support for forms and data entry.
+ *
+ * @module components/ui-input
+ */
+
+import { AfriCodeComponent, registerComponent, html } from './base.js';
+
+export class AfriUIInput extends AfriCodeComponent {
+  static get observedAttributes() {
+    return ['label', 'placeholder', 'type', 'value', 'disabled', 'error'];
+  }
+
+  constructor() {
+    super();
+    this.render();
+  }
+
+  connectedCallback() {
+    this._attachListeners();
+    this.loadStyles();
+  }
+
+  attributeChangedCallback() {
+    this.render();
+    this._attachListeners();
+  }
+
+  _attachListeners() {
+    const input = this.shadowRoot.querySelector('input');
+    if (!input) return;
+    input.addEventListener('input', () => {
+      this.emit('af-ui-input', { value: input.value });
+    });
+  }
+
+  render() {
+    const label = this.getAttribute('label') || '';
+    const placeholder = this.getAttribute('placeholder') || '';
+    const type = this.getAttribute('type') || 'text';
+    const value = this.getAttribute('value') || '';
+    const disabled = this.hasAttribute('disabled');
+    const error = this.getAttribute('error') || '';
+
+    this.shadowRoot.innerHTML = html`
+      <style>
+        :host { display: block; font-family: 'Inter', system-ui, sans-serif; }
+
+        label {
+          display: block;
+          font-size: 0.85rem;
+          font-weight: 600;
+          margin-bottom: 0.5rem;
+          color: #111827;
+        }
+
+        .field {
+          display: grid;
+          gap: 0.45rem;
+        }
+
+        input {
+          width: 100%;
+          border: 1px solid #d1d5db;
+          border-radius: 0.75rem;
+          padding: 0.95rem 1rem;
+          font-size: 0.95rem;
+          color: #111827;
+          background: #ffffff;
+          transition: border-color 150ms ease, box-shadow 150ms ease;
+        }
+
+        input:focus {
+          outline: none;
+          border-color: #2563eb;
+          box-shadow: 0 0 0 4px rgba(37, 99, 235, 0.12);
+        }
+
+        input:disabled {
+          opacity: 0.65;
+          cursor: not-allowed;
+          background: #f8fafc;
+        }
+
+        .error {
+          color: #dc2626;
+          font-size: 0.8rem;
+          min-height: 1rem;
+        }
+      </style>
+
+      <div class="field">
+        ${label ? html`<label>${label}</label>` : ''}
+        <input
+          type="${type}"
+          placeholder="${placeholder}"
+          value="${value}"
+          ${disabled ? 'disabled' : ''}
+          aria-invalid="${Boolean(error)}"
+        />
+        <div class="error">${error}</div>
+      </div>
+    `;
+  }
+}
+
+registerComponent('af-ui-input', AfriUIInput);
+export default AfriUIInput;

package/components/ui-switch.js

@@ -0,0 +1,85 @@
+/**
+ * AfriCode UI Switch
+ *
+ * A form control switch component with accessible state.
+ * @module components/ui-switch
+ */
+
+import { AfriCodeComponent, registerComponent, html } from './base.js';
+
+export class AfriUISwitch extends AfriCodeComponent {
+  static get observedAttributes() {
+    return ['checked', 'disabled', 'size'];
+  }
+
+  constructor() {
+    super();
+    this.render();
+  }
+
+  connectedCallback() {
+    this.shadowRoot.querySelector('button')?.addEventListener('click', (event) => {
+      if (this.hasAttribute('disabled')) return;
+      const next = !this.hasAttribute('checked');
+      if (next) {
+        this.setAttribute('checked', '');
+      } else {
+        this.removeAttribute('checked');
+      }
+      this.emit('af-ui-switch-toggle', { checked: next, originalEvent: event });
+    });
+  }
+
+  attributeChangedCallback() {
+    this.render();
+  }
+
+  render() {
+    const checked = this.hasAttribute('checked');
+    const disabled = this.hasAttribute('disabled');
+    const size = this.getAttribute('size') || 'md';
+    const dimensions = size === 'sm' ? { width: 36, height: 20, knob: 14 } : size === 'lg' ? { width: 56, height: 32, knob: 24 } : { width: 48, height: 28, knob: 20 };
+
+    const ariaChecked = checked ? 'true' : 'false';
+
+    this.shadowRoot.innerHTML = html`
+      <style>
+        :host { display: inline-block; }
+
+        button {
+          all: unset;
+          position: relative;
+          width: ${dimensions.width}px;
+          height: ${dimensions.height}px;
+          border-radius: ${dimensions.height / 2}px;
+          background: ${checked ? '#2563eb' : '#e5e7eb'};
+          cursor: ${disabled ? 'not-allowed' : 'pointer'};
+          transition: background 180ms ease;
+          box-shadow: inset 0 0 0 1px rgba(15, 23, 42, 0.08);
+        }
+
+        .knob {
+          position: absolute;
+          top: 50%;
+          left: ${checked ? `${dimensions.width - dimensions.knob - 4}px` : '4px'};
+          transform: translateY(-50%);
+          width: ${dimensions.knob}px;
+          height: ${dimensions.knob}px;
+          border-radius: 999px;
+          background: #ffffff;
+          transition: left 180ms ease;
+          box-shadow: 0 2px 6px rgba(15, 23, 42, 0.16);
+        }
+
+        button:disabled { opacity: 0.65; }
+      </style>
+
+      <button role="switch" aria-checked="${ariaChecked}" ${disabled ? 'disabled' : ''}>
+        <span class="knob"></span>
+      </button>
+    `;
+  }
+}
+
+registerComponent('af-ui-switch', AfriUISwitch);
+export default AfriUISwitch;

package/core/cli/commands/build.js

@@ -6,6 +6,35 @@ import { rm, cp, mkdir, readdir, writeFile } from 'fs/promises';
 import { existsSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { RawHtml } from '../../html.js';
+
+export async function normalizeRenderOutput(htmlContent) {
+    if (htmlContent && typeof htmlContent.text === 'function') {
+        return await htmlContent.text();
+    }
+
+    if (htmlContent instanceof RawHtml) {
+        return htmlContent.toString();
+    }
+
+    if (typeof htmlContent === 'string') {
+        return htmlContent;
+    }
+
+    if (htmlContent === null || htmlContent === undefined) {
+        return '';
+    }
+
+    if (typeof htmlContent === 'object') {
+        try {
+            return JSON.stringify(htmlContent);
+        } catch (err) {
+            return String(htmlContent);
+        }
+    }
+
+    return String(htmlContent);
+}
 
 export async function build() {
     logo();
@@ -90,7 +119,8 @@ export async function build() {
             }
 
             if (typeof pageModule.default === 'function') {
-                const htmlContent = pageModule.default({ data: loaderData });
+                let htmlContent = await pageModule.default({ data: loaderData });
+                htmlContent = await normalizeRenderOutput(htmlContent);
                 const outputPath = path.join(distDir, `${name}.html`);
                 await writeFile(outputPath, htmlContent);
                 const renderEnd = performance.now();

package/core/cli/commands/dev.js

@@ -1,13 +1,50 @@
 import { logo, colors } from '../ui.js';
 import * as nodePath from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createConnection } from 'node:net';
 import { createHMRServer } from '../../hmr.js';
 
+async function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ port, host: '127.0.0.1', timeout: 300 }, () => {
+            socket.destroy();
+            resolve(false);
+        });
+
+        socket.on('error', (err) => {
+            if (err.code === 'ECONNREFUSED' || err.code === 'EHOSTUNREACH' || err.code === 'ENETUNREACH') {
+                resolve(true);
+            } else {
+                resolve(false);
+            }
+        });
+
+        socket.on('timeout', () => {
+            socket.destroy();
+            resolve(true);
+        });
+    });
+}
+
+async function findAvailablePort(startPort, attempts = 10) {
+    for (let offset = 0; offset < attempts; offset++) {
+        const portToCheck = startPort + offset;
+        if (await isPortAvailable(portToCheck)) {
+            return portToCheck;
+        }
+    }
+    throw new Error(`No available ports found between ${startPort} and ${startPort + attempts - 1}`);
+}
+
 export async function dev() {
     logo();
     console.log(`${colors.green}▶ Starting development server...${colors.reset}\n`);
 
-    const PORT = process.env.PORT || 3000;
+    const desiredPort = Number(process.env.PORT) || 3000;
+    const PORT = await findAvailablePort(desiredPort, 10);
+    if (PORT !== desiredPort) {
+        console.log(`${colors.gold}⚠ Port ${desiredPort} was unavailable; using ${PORT} instead.${colors.reset}`);
+    }
     const __filename = fileURLToPath(import.meta.url);
     const __dirname = nodePath.dirname(__filename);
     const frameworkRoot = nodePath.resolve(__dirname, '../../../');