humanjs-core 1.0.0

package/README.md

@@ -0,0 +1,655 @@
+# 🦉 HumanJS Framework
+
+**A framework built for humans, not machines.**
+
+Simple. Readable. Easy to extend. Zero magic. No build tools required.
+
+---
+
+## 🌟 Philosophy
+
+HumanJS prioritizes human understanding over machine optimization.
+
+### Core Principles
+
+1. **Zero Magic** - Every behavior is traceable in ~200 lines of code
+2. **Human-First API** - Read like English sentences
+3. **Minimal Abstractions** - Use native DOM APIs when possible
+4. **Easy to Extend** - Modify the source, don't fight it
+5. **No Heavy Dependencies** - Pure JavaScript (ES6+), browser APIs only
+
+---
+
+## 🚀 Quick Start
+
+### Install from npm
+
+```bash
+npm install humanjs-core
+```
+
+```javascript
+import { app, html, loadHuman } from 'humanjs-core';
+```
+
+### Create a new app
+
+```bash
+npx humanjs-core create my-app
+```
+
+Then:
+
+```bash
+cd my-app
+npm install
+npm start
+```
+
+Starter structure:
+
+```text
+src/
+  api/
+  components/
+  layouts/
+  routes/
+  styles/
+  app.js
+  main.js
+```
+
+It also uses the `@/` alias for local imports:
+
+```js
+import { homeRoute } from '@/routes/home.js';
+import { AppLayout } from '@/layouts/AppLayout.js';
+```
+
+The generated starter now ships with:
+- a real navbar
+- a real footer
+- branded HumanJS mark
+- Dracula-inspired theme
+- stronger default landing page
+
+### 1. Clone or Download
+
+```bash
+git clone https://github.com/kaiserofthenight/humanjs.git
+cd humanjs
+```
+
+### 2. Open in Browser
+
+```bash
+npm start
+```
+
+Then open `http://localhost:8000`.
+
+### 2. Host It
+
+This repo is ready for static hosting.
+
+- GitHub Pages: deploy the repository root as-is
+- Netlify/Vercel static deploy: publish the repository root
+- Shared demo URLs:
+  - `?example=human`
+  - `?example=routing`
+  - `?example=todo`
+  - `?example=api`
+
+### 3. Your First App
+
+```javascript
+import { app } from './src/index.js';
+
+app.simple({
+  state: { count: 0 },
+  template: `
+    <div style="padding: 40px; text-align: center;">
+      <h1>{count}</h1>
+      <button @click="count += 1">+1</button>
+    </div>
+  `
+});
+```
+
+**That's it!** No compilation, no bundling, no configuration.
+
+### 4. Lower-Level Control
+
+```javascript
+app.create({
+  state: { count: 0 },
+  render: (state) => {
+    const element = html`<button id="increment">${state.count}</button>`;
+    const events = {
+      '#increment': {
+        click: () => state.count += 1
+      }
+    };
+    return { element, events };
+  }
+});
+```
+
+### 5. Simple JS
+
+HumanJS also supports the same low-boilerplate style directly inside `.js` files.
+
+```javascript
+import { app } from 'humanjs-core';
+
+app.simple({
+  state: { count: 0, step: 1 },
+  template: `
+    <div>
+      <h1>{count}</h1>
+      <button @click="count -= step">-</button>
+      <button @click="count = 0">reset</button>
+      <button @click="count += step">+</button>
+    </div>
+  `
+});
+```
+
+Run it directly in the browser:
+
+```javascript
+import './examples/simple-js/app.js';
+```
+
+In this repo, that example is already the default one loaded by `npm start`.
+
+If you still want the file-based syntax:
+
+```bash
+humanjs compile examples/human-counter/app.human examples/human-counter/app.js
+```
+
+Routing example:
+
+```javascript
+import './examples/routing/app.js';
+```
+
+That example shows:
+- reusable components with `component(...)`
+- reusable layouts with `layout(...)`
+- route-level layouts
+- route params like `/user/:id`
+- query params via `getParams()`
+- redirects with `beforeEach`
+- protected routes
+- 404 handling
+
+---
+
+## 📚 Core Concepts
+
+### 1. Reactive State
+
+```javascript
+import { createState } from './src/index.js';
+
+const state = createState({ count: 0 }, (prop, value) => {
+  console.log(`${prop} changed to ${value}`);
+});
+
+state.count = 5; // Triggers callback
+```
+
+**Advanced state features:**
+
+```javascript
+// Watch specific properties
+state.$watch('count', (newVal, oldVal) => {
+  console.log(`Count: ${oldVal} → ${newVal}`);
+});
+
+// Computed properties
+state.$computed('double', function() {
+  return this.count * 2;
+});
+
+// Reset state
+state.$reset({ count: 0 });
+
+// Get raw state
+const raw = state.$raw();
+```
+
+### 2. HTML Rendering
+
+```javascript
+import { html } from './src/index.js';
+
+// Simple
+const greeting = html`<h1>Hello, World!</h1>`;
+
+// With dynamic values
+const count = 5;
+const counter = html`<div>Count: ${count}</div>`;
+
+// With arrays
+const items = ['Apple', 'Banana', 'Orange'];
+const list = html`
+  <ul>
+    ${items.map(item => html`<li>${item}</li>`)}
+  </ul>
+`;
+```
+
+**Conditional rendering:**
+
+```javascript
+import { when } from './src/index.js';
+
+when(
+  user.isLoggedIn,
+  () => html`<div>Welcome, ${user.name}!</div>`,
+  () => html`<div>Please log in</div>`
+);
+```
+
+**List rendering:**
+
+```javascript
+import { each } from './src/index.js';
+
+each(users, (user) => html`
+  <div class="user-card">
+    <h3>${user.name}</h3>
+    <p>${user.email}</p>
+  </div>
+`);
+```
+
+### 3. Components
+
+```javascript
+import { app, html, component, layout } from './src/index.js';
+
+const Card = component(({ title, body }) => html`
+  <section>
+    <h2>${title}</h2>
+    <p>${body}</p>
+  </section>
+`);
+
+const Page = layout(({ children }) => html`
+  <main class="page-shell">${children}</main>
+`);
+
+app.human({
+  render: () => Page({
+    children: Card({
+      title: 'Hello',
+      body: 'Components are just functions.'
+    })
+  })
+});
+```
+
+### 4. Event Handling
+
+```javascript
+app.human({
+  state: { query: '' },
+  actions: {
+    save({ event }) {
+      event.preventDefault();
+      const form = new FormData(event.target);
+      console.log(Object.fromEntries(form.entries()));
+    },
+    setQuery({ state, event }) {
+      state.query = event.target.value;
+    }
+  },
+  render: ({ state }) => html`
+    <form data-submit="save">
+      <input
+        name="query"
+        value="${state.query}"
+        data-input="setQuery"
+        placeholder="Type here"
+      />
+      <button type="submit">Save</button>
+    </form>
+  `
+});
+```
+
+**Event helpers:**
+
+```javascript
+import { on, debounce, throttle } from './src/index.js';
+
+// Debounce search input
+const handleSearch = debounce((e) => {
+  state.query = e.target.value;
+}, 300);
+
+// Throttle scroll events
+const handleScroll = throttle(() => {
+  console.log('Scrolling...');
+}, 100);
+```
+
+### 5. Routing
+
+```javascript
+import { createRouter, Link } from './src/index.js';
+
+const router = createRouter({
+  '/': () => html`<h1>Home Page</h1>`,
+  '/about': () => html`<h1>About Page</h1>`,
+  '/user/:id': (params) => html`<h1>User ${params.id}</h1>`,
+  '*': () => html`<h1>404 - Not Found</h1>`
+}, {
+  beforeEach: (to, from, params) => {
+    console.log(`Navigating from ${from} to ${to}`);
+  },
+  afterEach: (to, from, params) => {
+    console.log(`Navigated to ${to}`);
+  }
+});
+
+// Navigate programmatically
+router.navigate('/about');
+
+// Create links
+const link = Link('/about', 'About Us', 'nav-link');
+```
+
+---
+
+## 🔌 Plugins
+
+### Form Validation
+
+```javascript
+import { createValidator, rules, displayErrors } from './src/plugins/validator.js';
+
+const validator = createValidator({
+  email: [rules.required, rules.email],
+  password: [rules.required, rules.minLength(8)],
+  age: [rules.required, rules.number, rules.min(18)],
+  confirmPassword: [rules.required, rules.match('password', 'Password')]
+});
+
+const result = validator.validate(formData);
+
+if (!result.isValid) {
+  displayErrors(formElement, result.errors);
+} else {
+  // Submit form
+}
+```
+
+**Available rules:**
+- `required` - Field must have a value
+- `email` - Valid email format
+- `minLength(n)` - Minimum length
+- `maxLength(n)` - Maximum length
+- `min(n)` - Minimum numeric value
+- `max(n)` - Maximum numeric value
+- `pattern(regex, msg)` - Custom regex
+- `url` - Valid URL
+- `number` - Numeric value
+- `integer` - Integer value
+- `match(field, name)` - Match another field
+- `custom(fn, msg)` - Custom validation
+
+### HTTP Client
+
+```javascript
+import { createHttp, http } from './src/plugins/http.js';
+
+// Use default instance
+const { data } = await http.get('/api/users');
+await http.post('/api/users', { name: 'John' });
+await http.put('/api/users/1', { name: 'Jane' });
+await http.delete('/api/users/1');
+
+// Custom instance
+const api = createHttp({
+  baseURL: 'https://api.example.com',
+  headers: { 'Authorization': 'Bearer token' },
+  timeout: 10000,
+  onRequest: (config) => {
+    console.log('Request:', config);
+  },
+  onResponse: (response) => {
+    console.log('Response:', response);
+  },
+  onError: (error) => {
+    console.error('Error:', error);
+  }
+});
+
+const users = await api.get('/users');
+```
+
+### Storage
+
+```javascript
+import { local, session, createNamespace } from './src/plugins/storage.js';
+
+// LocalStorage (persists)
+local.set('user', { name: 'John', age: 30 });
+const user = local.get('user');
+local.remove('user');
+local.clear();
+
+// SessionStorage (cleared on close)
+session.set('token', 'abc123');
+const token = session.get('token');
+
+// Namespaced storage
+const appStorage = createNamespace('myapp');
+appStorage.local.set('settings', { theme: 'dark' });
+```
+
+---
+
+## 🛠️ Utilities
+
+```javascript
+import { helpers } from './src/index.js';
+
+// Generate unique ID
+const id = helpers.uid('todo'); // 'todo_1234567890_abc'
+
+// Deep clone
+const copy = helpers.clone(originalObject);
+
+// Deep merge
+const merged = helpers.merge(obj1, obj2, obj3);
+
+// Format date
+const formatted = helpers.formatDate(new Date(), 'YYYY-MM-DD HH:mm');
+
+// Sleep/delay
+await helpers.sleep(1000); // Wait 1 second
+
+// String utilities
+helpers.capitalize('hello'); // 'Hello'
+helpers.truncate('Long text...', 10); // 'Long text...'
+
+// Array utilities
+helpers.shuffle([1, 2, 3, 4, 5]);
+helpers.unique([1, 2, 2, 3, 3]); // [1, 2, 3]
+helpers.groupBy(users, 'role');
+
+// Object utilities
+helpers.get(obj, 'user.address.city', 'Unknown');
+helpers.set(obj, 'user.name', 'John');
+helpers.pick(obj, ['name', 'email']);
+helpers.omit(obj, ['password', 'token']);
+
+// Async utilities
+await helpers.waitFor(() => element.isReady, 5000);
+await helpers.retry(() => fetchData(), 3, 1000);
+```
+
+---
+
+## 📦 Project Structure
+
+```
+humanjs-framework/
+├── index.html              # Demo page
+├── README.md              # This file
+│
+├── src/                   # Framework source
+│   ├── core/             # Core modules
+│   │   ├── state.js      # Reactive state
+│   │   ├── render.js     # HTML rendering
+│   │   ├── component.js  # Components
+│   │   ├── router.js     # SPA routing
+│   │   └── events.js     # Event handling
+│   │
+│   ├── plugins/          # Optional plugins
+│   │   ├── validator.js  # Form validation
+│   │   ├── http.js       # HTTP client
+│   │   └── storage.js    # Storage wrapper
+│   │
+│   ├── utils/            # Utilities
+│   │   └── helpers.js    # Helper functions
+│   │
+│   └── index.js          # Main entry point
+│
+└── examples/             # Example apps
+    ├── todo-app/
+    │   └── app.js
+    └── api-example/
+        └── app.js
+```
+
+---
+
+## 🎓 Examples
+
+### Todo App
+
+A complete todo application with:
+- Add, edit, delete todos
+- Mark as complete
+- Filter (all, active, completed)
+- LocalStorage persistence
+- Form validation
+
+[View Source](./examples/todo-app/app.js)
+
+### API Integration
+
+Demonstrates API usage with:
+- Fetch users from API
+- Loading states
+- Error handling
+- Search and filter
+- Debounced input
+
+[View Source](./examples/api-example/app.js)
+
+---
+
+## 🆚 Comparison with Other Frameworks
+
+### vs React
+
+| Feature | HumanJS | React |
+|---------|---------|-------|
+| Learning curve | 1 day | 1-2 weeks |
+| Setup | Open HTML file | Complex build setup |
+| Bundle size | ~5KB | ~40KB (min) |
+| Abstraction | Minimal | Heavy (JSX, virtual DOM) |
+| Debugging | Trace in source | Complex stack traces |
+
+### vs Vue
+
+| Feature | HumanJS | Vue |
+|---------|---------|-----|
+| Template syntax | Native HTML | Custom directives |
+| Reactivity | Proxy (native) | Proxy + compiler |
+| Components | Functions | Classes/objects |
+| Build step | None | Required for SFC |
+
+### vs Svelte
+
+| Feature | HumanJS | Svelte |
+|---------|---------|--------|
+| Compilation | None | Required |
+| Runtime size | ~5KB | ~2KB |
+| Learning curve | 1 day | 3-4 days |
+| Debugging | Browser native | Compiled output |
+
+### When to use HumanJS
+
+✅ **Use when:**
+- Building simple to medium apps
+- Learning frontend concepts
+- Prototyping quickly
+- Want full control
+- No build step desired
+
+❌ **Don't use when:**
+- Building complex enterprise apps
+- Need large ecosystem
+- Team requires specific framework experience
+- Need SSR or mobile apps
+
+---
+
+## 🔮 Future Improvements
+
+### Optional Enhancements
+
+1. **Virtual DOM** - For better performance
+2. **TypeScript** - Type definitions
+3. **SSR Support** - Server-side rendering
+4. **Dev Tools** - Browser extension
+5. **Plugin System** - Third-party plugins
+6. **CLI Tool** - Project scaffolding
+
+### How to Extend
+
+The framework is designed to be modified:
+
+1. Fork the repository
+2. Modify `src/` files directly
+3. Add new plugins in `src/plugins/`
+4. Share your improvements!
+
+---
+
+## License
+
+MIT License - do whatever you want with it!
+
+---
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Keep it simple
+2. Maintain readability
+3. Add tests for new features
+4. Update documentation
+
+---
+
+## Support
+
+- 📧 Email: abderrazzak.elouazghi@gmail.com
+- 🐛 Issues: [GitHub Issues](https://github.com/kaiserofthenight/humanjs/issues)
+- 💬 Discussions: [GitHub Discussions](https://github.com/kaiserofthenight/humanjs/discussions)
+- ⭐ Star us on GitHub!
+
+---
+
+**Remember: Frameworks are tools, not religions. Use what makes you productive!** 🚀