humanjs-core 1.0.0

package/src/core/render.js

@@ -0,0 +1,173 @@
+/**
+ * HTML RENDERING SYSTEM
+ * 
+ * Convert tagged template literals into real DOM elements.
+ * Supports dynamic values, nested elements, and arrays.
+ */
+
+/**
+ * Main html tagged template function
+ * @param {Array} strings - Template string parts
+ * @param  {...any} values - Dynamic values
+ * @returns {HTMLElement} DOM element
+ */
+export function html(strings, ...values) {
+  // Build complete HTML string
+  let htmlString = '';
+  
+  strings.forEach((str, i) => {
+    htmlString += str;
+    
+    if (i < values.length) {
+      const value = values[i];
+      
+      // Handle different value types
+      if (value === null || value === undefined) {
+        htmlString += '';
+      } else if (Array.isArray(value)) {
+        // For arrays, join DOM elements
+        htmlString += value.map(v => {
+          if (v instanceof HTMLElement) {
+            return v.outerHTML;
+          }
+          return String(v);
+        }).join('');
+      } else if (value instanceof HTMLElement) {
+        htmlString += value.outerHTML;
+      } else {
+        htmlString += String(value);
+      }
+    }
+  });
+  
+  // Create DOM from string
+  return createElementFromHTML(htmlString.trim());
+}
+
+/**
+ * Create a DOM element from HTML string
+ * @param {String} htmlString - HTML markup
+ * @returns {HTMLElement} DOM element
+ */
+function createElementFromHTML(htmlString) {
+  const template = document.createElement('template');
+  template.innerHTML = htmlString;
+  
+  const element = template.content.firstChild;
+  
+  if (!element) {
+    throw new Error('Invalid HTML: ' + htmlString);
+  }
+  
+  return element;
+}
+
+/**
+ * Create element with props (alternative to html``)
+ * @param {String} tag - Element tag name
+ * @param {Object} props - Element properties
+ * @param  {...any} children - Child elements
+ * @returns {HTMLElement}
+ */
+export function createElement(tag, props = {}, ...children) {
+  const element = document.createElement(tag);
+  
+  // Apply props
+  Object.keys(props).forEach(key => {
+    if (key === 'className') {
+      element.className = props[key];
+    } else if (key === 'style' && typeof props[key] === 'object') {
+      Object.assign(element.style, props[key]);
+    } else if (key.startsWith('on')) {
+      const eventName = key.substring(2).toLowerCase();
+      element.addEventListener(eventName, props[key]);
+    } else {
+      element.setAttribute(key, props[key]);
+    }
+  });
+  
+  // Append children
+  children.forEach(child => {
+    if (child === null || child === undefined) return;
+    
+    if (typeof child === 'string') {
+      element.appendChild(document.createTextNode(child));
+    } else if (child instanceof HTMLElement) {
+      element.appendChild(child);
+    } else if (Array.isArray(child)) {
+      child.forEach(c => {
+        if (c instanceof HTMLElement) {
+          element.appendChild(c);
+        } else {
+          element.appendChild(document.createTextNode(String(c)));
+        }
+      });
+    } else {
+      element.appendChild(document.createTextNode(String(child)));
+    }
+  });
+  
+  return element;
+}
+
+/**
+ * Render multiple children
+ * @param  {...any} children 
+ * @returns {DocumentFragment}
+ */
+export function fragment(...children) {
+  const frag = document.createDocumentFragment();
+  
+  children.forEach(child => {
+    if (child instanceof HTMLElement) {
+      frag.appendChild(child);
+    } else if (typeof child === 'string') {
+      frag.appendChild(document.createTextNode(child));
+    }
+  });
+  
+  return frag;
+}
+
+/**
+ * Conditionally render elements
+ * @param {Boolean} condition 
+ * @param {Function} trueRender 
+ * @param {Function} falseRender 
+ * @returns {HTMLElement}
+ */
+export function when(condition, trueRender, falseRender = () => html`<span></span>`) {
+  return condition ? trueRender() : falseRender();
+}
+
+/**
+ * Render list of items
+ * @param {Array} items 
+ * @param {Function} renderItem 
+ * @returns {Array<HTMLElement>}
+ */
+export function each(items, renderItem) {
+  return items.map((item, index) => renderItem(item, index));
+}
+
+/**
+ * Create a reusable view component
+ * @param {Function} renderFn
+ * @returns {Function}
+ */
+export function component(renderFn) {
+  return function HumanComponent(props = {}) {
+    return renderFn(props);
+  };
+}
+
+/**
+ * Create a reusable layout
+ * @param {Function} renderFn
+ * @returns {Function}
+ */
+export function layout(renderFn) {
+  return function HumanLayout(props = {}) {
+    return renderFn(props);
+  };
+}

package/src/core/router.js

@@ -0,0 +1,274 @@
+/**
+ * SPA ROUTING SYSTEM
+ * 
+ * Hash-based routing for single page applications.
+ * No server configuration required.
+ */
+
+import { createApp } from './component.js';
+
+/**
+ * Create a router
+ * @param {Object} routes - Route definitions { '/path': component }
+ * @param {Object} options - Router options
+ */
+export function createRouter(routes, options = {}) {
+  const {
+    root = document.getElementById('app'),
+    notFound = () => {
+      const el = document.createElement('div');
+      el.innerHTML = '<h1>404 - Page Not Found</h1>';
+      return el;
+    },
+    beforeEach = null,
+    afterEach = null
+  } = options;
+  
+  let currentRoute = null;
+  let currentComponent = null;
+  let isRedirecting = false;
+
+  function applyLayoutSync(layoutFn, content, context) {
+    if (typeof layoutFn !== 'function') return content;
+    return layoutFn({ ...context, children: content });
+  }
+
+  async function applyLayout(layoutFn, content, context) {
+    if (typeof layoutFn !== 'function') return content;
+    return await layoutFn({ ...context, children: content });
+  }
+
+  function normalizeRouteEntry(route, params) {
+    const entry = routes[route] || notFound;
+
+    if (typeof entry === 'function') {
+      return {
+        type: 'view',
+        render: entry,
+        layout: null
+      };
+    }
+
+    if (entry && typeof entry === 'object') {
+      const hasAppConfig = 'state' in entry || 'actions' in entry || 'derived' in entry || 'onMount' in entry || 'onUpdate' in entry || 'onDestroy' in entry;
+      return {
+        type: hasAppConfig ? 'app' : 'view',
+        render: entry.render || notFound,
+        layout: entry.layout || null,
+        state: entry.state,
+        derived: entry.derived,
+        actions: entry.actions,
+        onMount: entry.onMount,
+        onUpdate: entry.onUpdate,
+        onDestroy: entry.onDestroy
+      };
+    }
+
+    return {
+      type: 'view',
+      render: notFound,
+      layout: null
+    };
+  }
+
+  function getCurrentPath() {
+    const hash = window.location.hash.slice(1) || '/';
+    const [path] = hash.split('?');
+    return path || '/';
+  }
+  
+  // Parse route params (e.g., /user/:id)
+  function matchRoute(hash) {
+    const [pathOnly] = (hash.slice(1) || '/').split('?');
+    const path = pathOnly || '/';
+    
+    // Try exact match first
+    if (routes[path]) {
+      return { route: path, params: {} };
+    }
+    
+    // Try parameterized routes
+    for (const route in routes) {
+      const paramNames = [];
+      const regexPattern = route.replace(/:([^/]+)/g, (_, paramName) => {
+        paramNames.push(paramName);
+        return '([^/]+)';
+      });
+      
+      const regex = new RegExp(`^${regexPattern}$`);
+      const match = path.match(regex);
+      
+      if (match) {
+        const params = {};
+        paramNames.forEach((name, index) => {
+          params[name] = match[index + 1];
+        });
+        return { route, params };
+      }
+    }
+    
+    return null;
+  }
+  
+  // Navigate to a route
+  function navigate(path, replace = false) {
+    if (replace) {
+      const normalized = path.startsWith('#') ? path : `#${path}`;
+      window.history.replaceState(null, '', normalized);
+      render();
+    } else {
+      window.location.hash = path;
+    }
+  }
+  
+  // Render current route
+  async function render() {
+    const hash = window.location.hash;
+    const match = matchRoute(hash);
+    
+    let route, params;
+    if (match) {
+      route = match.route;
+      params = match.params;
+    } else {
+      route = '*';
+      params = {};
+    }
+    
+    // Call beforeEach guard
+    if (beforeEach) {
+      const result = beforeEach(route, currentRoute, params);
+      if (result === false) return;
+      if (typeof result === 'string' && !isRedirecting) {
+        isRedirecting = true;
+        navigate(result, true);
+        isRedirecting = false;
+        return;
+      }
+    }
+    
+    const routeEntry = normalizeRouteEntry(route, params);
+    
+    // Destroy previous component
+    if (currentComponent && currentComponent.destroy) {
+      currentComponent.destroy();
+    }
+    
+    // Clear root
+    root.innerHTML = '';
+    
+    // Render new component
+    if (typeof routeEntry.render === 'function') {
+      const context = { route, params, path: getCurrentPath(), query: getParams() };
+      const renderToken = Symbol('route-render');
+      render.activeToken = renderToken;
+
+      if (routeEntry.type === 'app') {
+        currentComponent = createApp({
+          root,
+          state: typeof routeEntry.state === 'function' ? routeEntry.state(params, context) : (routeEntry.state || {}),
+          derived: routeEntry.derived || {},
+          actions: routeEntry.actions || {},
+          onMount: routeEntry.onMount,
+          onUpdate: routeEntry.onUpdate,
+          onDestroy: routeEntry.onDestroy,
+          render: (appContext) => {
+            const content = routeEntry.render(params, { ...context, ...appContext });
+            return applyLayoutSync(routeEntry.layout, content, { ...context, ...appContext });
+          }
+        });
+        return;
+      }
+
+      const element = await routeEntry.render(params, context);
+      const layouted = await applyLayout(routeEntry.layout, element, context);
+
+      if (render.activeToken !== renderToken) {
+        return;
+      }
+      
+      if (layouted instanceof HTMLElement) {
+        root.appendChild(layouted);
+      } else if (layouted && layouted.element) {
+        currentComponent = layouted;
+        root.appendChild(layouted.element);
+      } else if (element instanceof HTMLElement) {
+        root.appendChild(element);
+      } else if (element && element.element) {
+        currentComponent = element;
+        root.appendChild(element.element);
+      }
+    }
+    
+    const previousRoute = currentRoute;
+    currentRoute = route;
+    
+    // Call afterEach hook
+    if (afterEach) {
+      afterEach(route, previousRoute, params);
+    }
+  }
+  
+  // Listen for hash changes
+  window.addEventListener('hashchange', render);
+  
+  // Initial render
+  render();
+  
+  // Return router API
+  return {
+    navigate,
+    back: () => window.history.back(),
+    forward: () => window.history.forward(),
+    getCurrentRoute: () => currentRoute,
+    getCurrentPath,
+    destroy: () => {
+      window.removeEventListener('hashchange', render);
+    }
+  };
+}
+
+/**
+ * Link component for navigation
+ */
+export function Link(to, text, className = '') {
+  const link = document.createElement('a');
+  link.href = `#${to}`;
+  link.textContent = text;
+  link.className = className;
+  
+  // Prevent default and use router navigation
+  link.addEventListener('click', (e) => {
+    e.preventDefault();
+    window.location.hash = to;
+  });
+  
+  return link;
+}
+
+/**
+ * Get route params from URL
+ */
+export function getParams() {
+  const hash = window.location.hash.slice(1);
+  const [path, query] = hash.split('?');
+  
+  if (!query) return {};
+  
+  return query.split('&').reduce((params, param) => {
+    const [key, value] = param.split('=');
+    params[decodeURIComponent(key)] = decodeURIComponent(value || '');
+    return params;
+  }, {});
+}
+
+/**
+ * Build URL with query params
+ */
+export function buildUrl(path, params = {}) {
+  const query = Object.keys(params)
+    .map(key => `${encodeURIComponent(key)}=${encodeURIComponent(params[key])}`)
+    .join('&');
+  
+  return query ? `${path}?${query}` : path;
+}

package/src/core/state.js

@@ -0,0 +1,114 @@
+/**
+ * REACTIVE STATE MANAGEMENT
+ * 
+ * Creates observable state objects that trigger callbacks on changes.
+ * Uses JavaScript Proxy to intercept property access and modifications.
+ */
+
+/**
+ * Create a reactive state object
+ * @param {Object} initialState - Initial state values
+ * @param {Function} onChange - Callback fired on any state change
+ * @returns {Proxy} Reactive state object
+ */
+export function createState(initialState = {}, onChange = null) {
+  // Store the raw state
+  const state = { ...initialState };
+  
+  // Store computed properties
+  const computed = {};
+  
+  // Store watchers for specific properties
+  const watchers = {};
+  
+  // Create reactive proxy
+  const proxy = new Proxy(state, {
+    get(target, property) {
+      // Return computed value if it exists
+      if (computed[property]) {
+        return computed[property]();
+      }
+      return target[property];
+    },
+    
+    set(target, property, value) {
+      const oldValue = target[property];
+      
+      // Only update if value actually changed
+      if (oldValue === value) return true;
+      
+      // Update the value
+      target[property] = value;
+      
+      // Call property-specific watchers
+      if (watchers[property]) {
+        watchers[property].forEach(watcher => {
+          watcher(value, oldValue);
+        });
+      }
+      
+      // Call global onChange callback
+      if (onChange) {
+        onChange(property, value, oldValue);
+      }
+      
+      return true;
+    }
+  });
+  
+  // Add utility methods
+  proxy.$watch = function(property, callback) {
+    if (!watchers[property]) {
+      watchers[property] = [];
+    }
+    watchers[property].push(callback);
+    
+    // Return unwatch function
+    return () => {
+      const index = watchers[property].indexOf(callback);
+      if (index > -1) {
+        watchers[property].splice(index, 1);
+      }
+    };
+  };
+  
+  proxy.$computed = function(property, computeFn) {
+    computed[property] = computeFn.bind(proxy);
+  };
+  
+  proxy.$reset = function(newState = initialState) {
+    Object.keys(state).forEach(key => delete state[key]);
+    Object.assign(state, newState);
+    if (onChange) onChange('$reset', newState);
+  };
+  
+  proxy.$raw = function() {
+    return { ...state };
+  };
+  
+  return proxy;
+}
+
+/**
+ * Create a global store (shared state across components)
+ */
+export function createStore(initialState = {}) {
+  const listeners = [];
+  const state = createState(initialState, (prop, value) => {
+    listeners.forEach(listener => listener(prop, value, state));
+  });
+  
+  return {
+    state,
+    subscribe(callback) {
+      listeners.push(callback);
+      return () => {
+        const index = listeners.indexOf(callback);
+        if (index > -1) listeners.splice(index, 1);
+      };
+    },
+    getState() {
+      return state.$raw();
+    }
+  };
+}

package/src/index.js

@@ -0,0 +1,61 @@
+/**
+ * HUMANJS FRAMEWORK
+ * 
+ * A human-first frontend framework.
+ * Simple, readable, and easy to extend.
+ * 
+ * @version 1.0.0
+ * @author HumanJS Team
+ */
+
+// Core modules
+export { createState, createStore } from './core/state.js';
+export { html, createElement, fragment, when, each, component, layout } from './core/render.js';
+export { createComponent, createApp, createSimpleApp, app } from './core/component.js';
+export { createRouter, Link, getParams, buildUrl } from './core/router.js';
+export { attachEvents, delegate, debounce, throttle, on, mergeEvents } from './core/events.js';
+export { parseHumanFile, compileTemplate, compileHuman, createRuntimeTemplate, loadHuman } from './compiler/human.js';
+
+// Plugins
+export { createValidator, rules, getFormData, displayErrors } from './plugins/validator.js';
+export { createHttp, http } from './plugins/http.js';
+export { local, session, createNamespace, onStorageChange } from './plugins/storage.js';
+
+// Utilities
+export * as helpers from './utils/helpers.js';
+
+/**
+ * Framework version
+ */
+export const VERSION = '1.0.0';
+
+/**
+ * Quick start helper
+ */
+export function humanjs() {
+  console.log(`
+    🎯 HumanJS Framework v${VERSION}
+    
+    A framework built for humans, not machines.
+    
+    Quick start:
+    import { loadHuman } from './src/index.js';
+    
+    loadHuman('./examples/human-counter/app.human');
+    
+    Documentation: https://github.com/kaiserofthenight/humanjs
+  `);
+}
+
+/**
+ * Global error handler (optional)
+ */
+if (typeof window !== 'undefined') {
+  window.addEventListener('error', (event) => {
+    console.error('[HumanJS] Uncaught error:', event.error);
+  });
+  
+  window.addEventListener('unhandledrejection', (event) => {
+    console.error('[HumanJS] Unhandled promise rejection:', event.reason);
+  });
+}