@kaiserofthenight/human-js 1.0.0

package/src/core/events.js

@@ -0,0 +1,130 @@
+/**
+ * EVENT HANDLING SYSTEM
+ * 
+ * Attach and manage DOM event listeners.
+ * Supports event delegation and automatic cleanup.
+ */
+
+/**
+ * Attach events to DOM elements
+ * @param {HTMLElement} rootElement 
+ * @param {Object} eventMap - { selector: { eventType: handler } }
+ */
+export function attachEvents(rootElement, eventMap = {}) {
+  const attachedListeners = [];
+  
+  Object.keys(eventMap).forEach(selector => {
+    const events = eventMap[selector];
+    
+    // Find target element
+    let targetElement;
+    if (selector === 'root' || selector === ':root') {
+      targetElement = rootElement;
+    } else {
+      targetElement = rootElement.querySelector(selector);
+    }
+    
+    if (!targetElement) {
+      console.warn(`[HumanJS] Element not found: ${selector}`);
+      return;
+    }
+    
+    // Attach each event type
+    Object.keys(events).forEach(eventType => {
+      const handler = events[eventType];
+      targetElement.addEventListener(eventType, handler);
+      
+      // Store for cleanup
+      attachedListeners.push({
+        element: targetElement,
+        type: eventType,
+        handler
+      });
+    });
+  });
+  
+  // Return cleanup function
+  return () => {
+    attachedListeners.forEach(({ element, type, handler }) => {
+      element.removeEventListener(type, handler);
+    });
+  };
+}
+
+/**
+ * Event delegation - attach one listener to parent
+ * @param {HTMLElement} parent 
+ * @param {String} eventType 
+ * @param {String} selector 
+ * @param {Function} handler 
+ */
+export function delegate(parent, eventType, selector, handler) {
+  const listener = (event) => {
+    const target = event.target.closest(selector);
+    if (target && parent.contains(target)) {
+      handler.call(target, event);
+    }
+  };
+  
+  parent.addEventListener(eventType, listener);
+  
+  return () => parent.removeEventListener(eventType, listener);
+}
+
+/**
+ * Debounce function calls
+ * @param {Function} fn 
+ * @param {Number} delay 
+ */
+export function debounce(fn, delay = 300) {
+  let timeoutId;
+  return function(...args) {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => fn.apply(this, args), delay);
+  };
+}
+
+/**
+ * Throttle function calls
+ * @param {Function} fn 
+ * @param {Number} limit 
+ */
+export function throttle(fn, limit = 300) {
+  let inThrottle;
+  return function(...args) {
+    if (!inThrottle) {
+      fn.apply(this, args);
+      inThrottle = true;
+      setTimeout(() => inThrottle = false, limit);
+    }
+  };
+}
+
+/**
+ * Common event helpers
+ */
+export const on = {
+  click: (selector, handler) => ({ [selector]: { click: handler } }),
+  input: (selector, handler) => ({ [selector]: { input: handler } }),
+  submit: (selector, handler) => ({ 
+    [selector]: { 
+      submit: (e) => {
+        e.preventDefault();
+        handler(e);
+      }
+    }
+  }),
+  change: (selector, handler) => ({ [selector]: { change: handler } }),
+  focus: (selector, handler) => ({ [selector]: { focus: handler } }),
+  blur: (selector, handler) => ({ [selector]: { blur: handler } }),
+  keydown: (selector, handler) => ({ [selector]: { keydown: handler } }),
+  keyup: (selector, handler) => ({ [selector]: { keyup: handler } })
+};
+
+/**
+ * Merge multiple event maps
+ * @param  {...Object} eventMaps 
+ */
+export function mergeEvents(...eventMaps) {
+  return Object.assign({}, ...eventMaps);
+}

package/src/core/render.js

@@ -0,0 +1,151 @@
+/**
+ * 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));
+}

package/src/core/router.js

@@ -0,0 +1,182 @@
+/**
+ * SPA ROUTING SYSTEM
+ * 
+ * Hash-based routing for single page applications.
+ * No server configuration required.
+ */
+
+/**
+ * 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;
+  
+  // Parse route params (e.g., /user/:id)
+  function matchRoute(hash) {
+    const path = hash.slice(1) || '/';
+    
+    // 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) {
+      window.location.replace(`#${path}`);
+    } else {
+      window.location.hash = path;
+    }
+  }
+  
+  // Render current route
+  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; // Cancel navigation
+    }
+    
+    // Get route component
+    const routeComponent = routes[route] || notFound;
+    
+    // Destroy previous component
+    if (currentComponent && currentComponent.destroy) {
+      currentComponent.destroy();
+    }
+    
+    // Clear root
+    root.innerHTML = '';
+    
+    // Render new component
+    if (typeof routeComponent === 'function') {
+      const element = routeComponent(params);
+      
+      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,
+    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,63 @@
+/**
+ * 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 } from './core/render.js';
+export { createComponent, 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';
+
+// 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 { app, html } from './src/index.js';
+    
+    app.create({
+      state: { count: 0 },
+      render: (state) => html\`<div>\${state.count}</div>\`
+    });
+    
+    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);
+  });
+}