frontend-hamroun 1.2.63 → 1.2.65

package/README.md

@@ -1,11 +1,7 @@
 # Frontend Hamroun
 
 <p align="center">
-  <img src="https://drive.google.com/uc?export=view&id=1zJV5tgl9p23VaNd5YeVF4Wx9v_oTdgZp" alt="Frontend Hamroun Logo" width="300">
-</p>
-
-<p align="center">
-  <code style="font-size: 24px; color: #4A90E2; background-color: transparent">{ Frontend Hamroun }</code>
+  <img src="https://drive.google.com/uc?export=view&id=15VsMSNDhWAfV_R6ZWJltOJd-RMs9UH_y" alt="Frontend Hamroun Logo" width="300">
 </p>
 
 A lightweight full-stack JavaScript framework with Virtual DOM and hooks implementation
@@ -15,21 +11,61 @@ A lightweight full-stack JavaScript framework with Virtual DOM and hooks impleme
 [![npm](https://img.shields.io/npm/dt/frontend-hamroun)](https://www.npmjs.com/package/frontend-hamroun)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-## Installation
+## 📋 Table of Contents
+
+- [Introduction](#-introduction)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Core Concepts](#-core-concepts)
+- [Frontend Features](#-frontend-features)
+- [Backend Features](#-backend-features)
+- [API Reference](#-api-reference)
+- [CLI Tools](#-cli-tools)
+- [Advanced Usage](#-advanced-usage)
+- [TypeScript Support](#-typescript-support)
+- [Browser Compatibility](#-browser-compatibility)
+- [FAQ](#-frequently-asked-questions)
+- [License](#-license)
+
+## 🚀 Introduction
+
+Frontend Hamroun is a lightweight (~5KB gzipped) JavaScript framework designed for building modern web applications. It combines React-like frontend development with powerful backend capabilities in a single, unified package.
+
+### Key Features
+
+- **Efficient Virtual DOM**: Minimizes DOM operations with intelligent diffing
+- **Complete Hooks API**: useState, useEffect, useRef, useMemo, and more
+- **Full-Stack Solution**: Unified frontend and backend development
+- **Server-Side Rendering**: Optimized SSR with hydration
+- **File-Based Routing**: Intuitive API endpoint creation
+- **Database Integration**: Built-in support for MongoDB, MySQL, PostgreSQL
+- **TypeScript Support**: Full type definitions and excellent DX
+- **Automatic Batch Updates**: Efficient state management
+- **CLI Tooling**: Scaffolding for components, pages, and API routes
+
+## 📦 Installation
 
 ```bash
+# Using npm
 npm install frontend-hamroun
+
+# Using yarn
+yarn add frontend-hamroun
+
+# Using pnpm
+pnpm add frontend-hamroun
 ```
 
-## Quick Start
+## 🏁 Quick Start
 
-Create a new project using:
+<details>
+<summary><b>Method 1: Create a new project with CLI</b></summary>
 
 ```bash
-# Using the create-frontend-app command
+# Using npx
 npx create-frontend-app my-app
 
-# Or using the frontend-hamroun CLI
+# Or with the frontend-hamroun CLI
 npx frontend-hamroun create my-app
 ```
 
@@ -41,256 +77,1171 @@ npm install
 npm run dev
 ```
 
-## Basic Usage
+This will scaffold a new project with all the necessary configuration.
+</details>
+
+<details>
+<summary><b>Method 2: Add to an existing project</b></summary>
+
+```bash
+# Install the package
+npm install frontend-hamroun
+
+# Import and use in your code
+import { render, useState } from 'frontend-hamroun';
+```
 
 ```jsx
+// Create a simple app
 import { render, useState } from 'frontend-hamroun';
 
-function App() {
+function Counter() {
   const [count, setCount] = useState(0);
+  
   return (
     <div>
       <h1>Count: {count}</h1>
-      <button onClick={() => setCount(count + 1)}>Increment</button>
+      <button onClick={() => setCount(count + 1)}>
+        Increment
+      </button>
     </div>
   );
 }
 
-render(<App />, document.getElementById('root'));
+render(<Counter />, document.getElementById('root'));
 ```
+</details>
 
-## Features
+## 🧠 Core Concepts
 
-- **Lightweight Core**: <5KB gzipped for essential runtime
-- **Full-Stack Solution**: Client and server capabilities in one package
-- **Virtual DOM**: Efficient rendering and diffing algorithm
-- **Hooks API**: Complete hooks system (useState, useEffect, useMemo, useRef)
-- **Context API**: Simple state management across components
-- **Server-Side Rendering**: Optimized SSR with hydration
-- **Database Integration**: Support for MongoDB, MySQL, and PostgreSQL
-- **Authentication**: Built-in JWT authentication system
-- **API Routing**: Express-based file system routing
-- **TypeScript Support**: Full type definitions included
-- **Interactive CLI**: Powerful tools for project scaffolding and component creation
+### Virtual DOM
 
-## Client-side Features
+Frontend Hamroun uses a lightweight Virtual DOM implementation to efficiently update the real DOM. It only applies the minimal necessary changes by:
 
-### Component Development
+```jsx
+// Virtual DOM diffing occurs automatically
+function App() {
+  const [count, setCount] = useState(0);
+  return (
+    <div>
+      <h1>Counter</h1>
+      <p>Count: {count}</p> {/* Only this text node updates */}
+      <button onClick={() => setCount(count + 1)}>Increment</button>
+    </div>
+  );
+}
+```
+
+### Component Model
+
+Components are the building blocks of your UI. Each component encapsulates its own logic and rendering:
 
 ```jsx
-import { useState, useEffect } from 'frontend-hamroun';
+// Function components with hooks
+function Greeting({ name }) {
+  // State management
+  const [clicked, setClicked] = useState(false);
+  
+  // Side effects
+  useEffect(() => {
+    document.title = `Hello, ${name}`;
+    return () => { document.title = 'App'; };
+  }, [name]);
+  
+  return (
+    <div>
+      <h1>{clicked ? `Thanks, ${name}!` : `Hello, ${name}!`}</h1>
+      <button onClick={() => setClicked(true)}>
+        {clicked ? 'Clicked!' : 'Click me'}
+      </button>
+    </div>
+  );
+}
+```
+
+## 🎨 Frontend Features
+
+### Hooks System
+
+<details>
+<summary><b>State Management with useState</b></summary>
+
+```jsx
+import { useState } from 'frontend-hamroun';
 
 function Counter() {
   const [count, setCount] = useState(0);
   
+  function increment() {
+    setCount(count + 1);
+  }
+  
+  function decrement() {
+    setCount(count - 1);
+  }
+  
+  // Functional updates for derived state
+  function double() {
+    setCount(prevCount => prevCount * 2);
+  }
+  
+  return (
+    <div>
+      <h2>Count: {count}</h2>
+      <button onClick={increment}>+</button>
+      <button onClick={decrement}>-</button>
+      <button onClick={double}>×2</button>
+    </div>
+  );
+}
+```
+</details>
+
+<details>
+<summary><b>Side Effects with useEffect</b></summary>
+
+```jsx
+import { useState, useEffect } from 'frontend-hamroun';
+
+function UserProfile({ userId }) {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(true);
+  
   useEffect(() => {
-    document.title = `Count: ${count}`;
-    return () => document.title = 'App';
-  }, [count]);
+    // Reset state when userId changes
+    setLoading(true);
+    
+    // Fetch user data
+    fetch(`/api/users/${userId}`)
+      .then(res => res.json())
+      .then(data => {
+        setUser(data);
+        setLoading(false);
+      })
+      .catch(err => {
+        console.error(err);
+        setLoading(false);
+      });
+    
+    // Cleanup function runs on component unmount or before effect re-runs
+    return () => {
+      // Cancel any pending requests or subscriptions
+      console.log('Cleaning up effect for userId:', userId);
+    };
+  }, [userId]); // Only re-run when userId changes
+  
+  if (loading) return <div>Loading...</div>;
+  if (!user) return <div>User not found</div>;
   
   return (
-    <div className="counter">
-      <h2>Counter: {count}</h2>
-      <button onClick={() => setCount(count + 1)}>+</button>
-      <button onClick={() => setCount(count - 1)}>-</button>
+    <div>
+      <h1>{user.name}</h1>
+      <p>Email: {user.email}</p>
     </div>
   );
 }
 ```
+</details>
+
+<details>
+<summary><b>Performance Optimization with useMemo and useRef</b></summary>
 
-### Hooks API
+```jsx
+import { useState, useMemo, useRef } from 'frontend-hamroun';
 
-- **useState**: Manage component state
-- **useEffect**: Handle side effects
-- **useMemo**: Memoize expensive calculations
-- **useRef**: Reference DOM elements and persist values
-- **useErrorBoundary**: Create error boundaries
+function ExpensiveCalculation({ items, filter }) {
+  const [selectedId, setSelectedId] = useState(null);
+  
+  // Cache expensive calculation results, only recalculate when dependencies change
+  const filteredItems = useMemo(() => {
+    console.log('Filtering items...');
+    return items.filter(item => item.name.includes(filter));
+  }, [items, filter]);
+  
+  // Create a persistent reference that doesn't trigger re-renders
+  const lastRenderTime = useRef(Date.now());
+  
+  console.log(`Time since last render: ${Date.now() - lastRenderTime.current}ms`);
+  lastRenderTime.current = Date.now();
+  
+  // DOM element references
+  const listRef = useRef(null);
+  
+  function scrollToTop() {
+    listRef.current.scrollTop = 0;
+  }
+  
+  return (
+    <div>
+      <button onClick={scrollToTop}>Scroll to top</button>
+      <div ref={listRef} style={{ height: '200px', overflow: 'auto' }}>
+        {filteredItems.map(item => (
+          <div 
+            key={item.id}
+            onClick={() => setSelectedId(item.id)}
+            style={{ 
+              background: item.id === selectedId ? 'lightblue' : 'white'
+            }}
+          >
+            {item.name}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+</details>
 
-### Context API
+<details>
+<summary><b>Context API for State Management</b></summary>
 
 ```jsx
-// Create context
+import { createContext, useContext, useState } from 'frontend-hamroun';
+
+// Create a context with default value
 const ThemeContext = createContext('light');
 
-// Provider
-function App() {
+// Provider component to supply context value
+function ThemeProvider({ children }) {
   const [theme, setTheme] = useState('light');
   
+  const toggleTheme = () => {
+    setTheme(theme === 'light' ? 'dark' : 'light');
+  };
+  
   return (
-    <ThemeContext.Provider value={theme}>
-      <Header />
-      <Main />
-      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
-        Toggle theme
-      </button>
+    <ThemeContext.Provider value={{ theme, toggleTheme }}>
+      {children}
     </ThemeContext.Provider>
   );
 }
 
-// Consumer
-function Header() {
-  const theme = useContext(ThemeContext);
-  return <header className={theme}><h1>My App</h1></header>;
+// Consumer component using the context value
+function ThemedButton() {
+  const { theme, toggleTheme } = useContext(ThemeContext);
+  
+  return (
+    <button 
+      onClick={toggleTheme}
+      style={{ 
+        background: theme === 'light' ? '#fff' : '#333',
+        color: theme === 'light' ? '#333' : '#fff',
+        border: '1px solid #ccc',
+        padding: '8px 16px',
+      }}
+    >
+      Switch to {theme === 'light' ? 'dark' : 'light'} mode
+    </button>
+  );
+}
+
+// Usage in application
+function App() {
+  return (
+    <ThemeProvider>
+      <div>
+        <h1>Themed Application</h1>
+        <ThemedButton />
+      </div>
+    </ThemeProvider>
+  );
 }
 ```
+</details>
 
-## Server-Side Features
+<details>
+<summary><b>Error Boundaries with useErrorBoundary</b></summary>
+
+```jsx
+import { useErrorBoundary } from 'frontend-hamroun';
+
+function ErrorBoundary({ children }) {
+  const [error, resetError] = useErrorBoundary();
+  
+  if (error) {
+    return (
+      <div className="error-boundary">
+        <h2>Something went wrong</h2>
+        <p>{error.message}</p>
+        <button onClick={resetError}>Try again</button>
+      </div>
+    );
+  }
+  
+  return children;
+}
+
+// Usage
+function App() {
+  return (
+    <ErrorBoundary>
+      <UserProfile userId="123" />
+    </ErrorBoundary>
+  );
+}
+```
+</details>
+
+### Batch Updates for Efficiency
+
+Frontend Hamroun automatically batches state updates within event handlers and can manually batch other updates with `batchUpdates`:
+
+```jsx
+import { useState, batchUpdates } from 'frontend-hamroun';
+
+function Form() {
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [isSubmitting, setSubmitting] = useState(false);
+  const [errors, setErrors] = useState({});
+  
+  async function handleSubmit(e) {
+    e.preventDefault();
+    
+    // Group multiple state updates into a single render
+    batchUpdates(() => {
+      setSubmitting(true);
+      setErrors({});
+    });
+    
+    try {
+      const response = await fetch('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name, email })
+      });
+      
+      const result = await response.json();
+      
+      batchUpdates(() => {
+        setSubmitting(false);
+        setName('');
+        setEmail('');
+      });
+    } catch (error) {
+      batchUpdates(() => {
+        setSubmitting(false);
+        setErrors({ submit: error.message });
+      });
+    }
+  }
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* Form fields */}
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? 'Submitting...' : 'Submit'}
+      </button>
+    </form>
+  );
+}
+```
+
+## 🖥️ Backend Features
 
 ### Express Server Integration
 
+<details>
+<summary><b>Server Setup</b></summary>
+
 ```js
 import { server } from 'frontend-hamroun/server';
 
 const app = await server.createServer({
   port: 3000,
-  apiDir: './api',
-  pagesDir: './pages',
-  staticDir: './public',
+  apiDir: './api',        // Directory for API routes
+  pagesDir: './pages',    // Directory for page components
+  staticDir: './public',  // Directory for static files
+  
+  // Database configuration
   db: {
     url: process.env.DATABASE_URL,
-    type: 'mongodb' // or 'mysql', 'postgres'
+    type: 'mongodb'       // mongodb, mysql, or postgres
   },
+  
+  // Authentication configuration
   auth: {
     secret: process.env.JWT_SECRET,
-    expiresIn: '7d'
+    expiresIn: '7d'       // Token expiration time
   }
 });
 
 await app.start();
 console.log('Server running at http://localhost:3000');
 ```
+</details>
+
+### File-Based API Routing
 
-### API Routes
+<details>
+<summary><b>API Routes</b></summary>
 
 ```js
-// api/users.js - Automatically mapped to /api/users
+// api/users.js (automatically maps to /api/users)
 export async function get(req, res) {
+  // GET /api/users - List all users
   const users = await req.db.collection('users').find().toArray();
   res.json(users);
 }
 
 export async function post(req, res) {
+  // POST /api/users - Create a new user
   const { name, email } = req.body;
   
   if (!name || !email) {
     return res.status(400).json({ error: 'Name and email are required' });
   }
   
-  const result = await req.db.collection('users').insertOne({ name, email });
-  res.status(201).json(result);
+  const result = await req.db.collection('users').insertOne({
+    name,
+    email,
+    createdAt: new Date()
+  });
+  
+  res.status(201).json({ id: result.insertedId });
 }
 ```
 
-## Server-Side Rendering
+```js
+// api/users/[id].js (automatically maps to /api/users/:id)
+export async function get(req, res) {
+  // GET /api/users/:id - Get user by ID
+  const { id } = req.params;
+  
+  try {
+    const user = await req.db.collection('users').findOne({
+      _id: new ObjectId(id)
+    });
+    
+    if (!user) {
+      return res.status(404).json({ error: 'User not found' });
+    }
+    
+    res.json(user);
+  } catch (error) {
+    res.status(500).json({ error: 'Server error' });
+  }
+}
+
+export async function put(req, res) {
+  // PUT /api/users/:id - Update user
+  const { id } = req.params;
+  const { name, email } = req.body;
+  
+  await req.db.collection('users').updateOne(
+    { _id: new ObjectId(id) },
+    { $set: { name, email, updatedAt: new Date() } }
+  );
+  
+  res.json({ success: true });
+}
+
+export async function del(req, res) {
+  // DELETE /api/users/:id - Delete user
+  // Note: 'delete' is a reserved word, so we use 'del'
+  const { id } = req.params;
+  
+  await req.db.collection('users').deleteOne({
+    _id: new ObjectId(id)
+  });
+  
+  res.status(204).end();
+}
+```
+</details>
+
+### Database Integration
+
+<details>
+<summary><b>MongoDB Example</b></summary>
+
+```js
+// api/posts.js
+export async function get(req, res) {
+  // Complex MongoDB aggregation
+  const posts = await req.db.collection('posts')
+    .aggregate([
+      { $match: { published: true } },
+      { $sort: { createdAt: -1 } },
+      { $limit: 10 },
+      { $lookup: {
+        from: 'users',
+        localField: 'authorId',
+        foreignField: '_id',
+        as: 'author'
+      }},
+      { $unwind: '$author' },
+      { $project: {
+        title: 1,
+        content: 1,
+        createdAt: 1,
+        'author.name': 1,
+        'author.email': 1
+      }}
+    ])
+    .toArray();
+  
+  res.json(posts);
+}
+```
+</details>
+
+<details>
+<summary><b>MySQL Example</b></summary>
+
+```js
+// api/products.js
+export async function get(req, res) {
+  // Complex SQL query with joins
+  const [products] = await req.db.execute(`
+    SELECT 
+      p.id, 
+      p.name, 
+      p.price, 
+      c.name as categoryName
+    FROM 
+      products p
+    JOIN 
+      categories c ON p.category_id = c.id
+    WHERE 
+      p.active = ?
+    ORDER BY 
+      p.created_at DESC
+    LIMIT 20
+  `, [true]);
+  
+  res.json(products);
+}
+```
+</details>
+
+<details>
+<summary><b>PostgreSQL Example</b></summary>
+
+```js
+// api/analytics.js
+export async function get(req, res) {
+  // Advanced PostgreSQL features
+  const result = await req.db.query(`
+    WITH monthly_sales AS (
+      SELECT
+        date_trunc('month', order_date) as month,
+        SUM(total_amount) as revenue
+      FROM
+        orders
+      WHERE
+        order_date > NOW() - INTERVAL '1 year'
+      GROUP BY
+        date_trunc('month', order_date)
+    )
+    SELECT 
+      month,
+      revenue,
+      lag(revenue) OVER (ORDER BY month) as prev_month_revenue,
+      round((revenue - lag(revenue) OVER (ORDER BY month)) / 
+        lag(revenue) OVER (ORDER BY month) * 100, 2) as growth_percent
+    FROM
+      monthly_sales
+    ORDER BY
+      month
+  `);
+  
+  res.json(result.rows);
+}
+```
+</details>
+
+### Authentication System
+
+<details>
+<summary><b>JWT Authentication</b></summary>
+
+```js
+// api/auth/login.js
+export async function post(req, res) {
+  const { email, password } = req.body;
+  
+  // Validate input
+  if (!email || !password) {
+    return res.status(400).json({ error: 'Email and password are required' });
+  }
+  
+  try {
+    // Find user by email
+    const user = await req.db.collection('users').findOne({ email });
+    
+    // Check if user exists and password is correct
+    if (!user || !await req.auth.comparePasswords(password, user.password)) {
+      return res.status(401).json({ error: 'Invalid credentials' });
+    }
+    
+    // Generate JWT token
+    const token = req.auth.generateToken({
+      id: user._id,
+      name: user.name,
+      email: user.email,
+      roles: user.roles || ['user']
+    });
+    
+    // Return token and user info (excluding sensitive data)
+    res.json({
+      token,
+      user: {
+        id: user._id,
+        name: user.name,
+        email: user.email,
+        roles: user.roles || ['user']
+      }
+    });
+  } catch (error) {
+    res.status(500).json({ error: 'Authentication failed' });
+  }
+}
+```
+
+```js
+// api/auth/register.js
+export async function post(req, res) {
+  const { name, email, password } = req.body;
+  
+  // Validate input
+  if (!name || !email || !password) {
+    return res.status(400).json({ 
+      error: 'Name, email, and password are required' 
+    });
+  }
+  
+  try {
+    // Check if user already exists
+    const existingUser = await req.db.collection('users').findOne({ email });
+    if (existingUser) {
+      return res.status(409).json({ error: 'Email already in use' });
+    }
+    
+    // Hash password
+    const hashedPassword = await req.auth.hashPassword(password);
+    
+    // Create user
+    const result = await req.db.collection('users').insertOne({
+      name,
+      email,
+      password: hashedPassword,
+      roles: ['user'],
+      createdAt: new Date()
+    });
+    
+    res.status(201).json({ 
+      id: result.insertedId,
+      name,
+      email,
+      roles: ['user']
+    });
+  } catch (error) {
+    res.status(500).json({ error: 'Registration failed' });
+  }
+}
+```
+
+```js
+// middleware/requireAuth.js - Protected route middleware
+export default function requireAuth(req, res, next) {
+  const token = req.headers.authorization?.split(' ')[1];
+  
+  if (!token) {
+    return res.status(401).json({ error: 'Authentication required' });
+  }
+  
+  try {
+    // Verify token
+    const decoded = req.auth.verifyToken(token);
+    req.user = decoded; // Attach user to request
+    next();
+  } catch (error) {
+    return res.status(401).json({ error: 'Invalid or expired token' });
+  }
+}
+
+// api/profile.js - Protected route example
+import requireAuth from '../middleware/requireAuth.js';
+
+export const middleware = [requireAuth];
+
+export async function get(req, res) {
+  // req.user is available from requireAuth middleware
+  const { id } = req.user;
+  
+  const profile = await req.db.collection('users').findOne(
+    { _id: new ObjectId(id) },
+    { projection: { password: 0 } } // Exclude password
+  );
+  
+  res.json(profile);
+}
+```
+</details>
+
+## 🔄 Server-Side Rendering
+
+Frontend Hamroun provides built-in server-side rendering capabilities to improve performance and SEO:
+
+<details>
+<summary><b>Server-Side Rendering Setup</b></summary>
 
 ```jsx
-// Server-side
+// server.js
+import express from 'express';
 import { renderToString } from 'frontend-hamroun/ssr';
 import App from './App';
 
+const app = express();
+app.use(express.static('public'));
+
 app.get('*', async (req, res) => {
+  // Render app to string
   const html = await renderToString(<App url={req.url} />);
   
+  // Send complete HTML document
   res.send(`
     <!DOCTYPE html>
     <html>
       <head>
         <title>My SSR App</title>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
         <link rel="stylesheet" href="/styles.css">
       </head>
       <body>
         <div id="root">${html}</div>
-        <script src="/client.js"></script>
+        <script src="/bundle.js"></script>
       </body>
     </html>
   `);
 });
 
-// Client-side
+app.listen(3000, () => {
+  console.log('Server running at http://localhost:3000');
+});
+
+// client.js (for hydration)
 import { hydrate } from 'frontend-hamroun';
 import App from './App';
 
+// Hydrate the app in the browser
 hydrate(<App url={window.location.pathname} />, document.getElementById('root'));
 ```
+</details>
 
-## Performance Features
+## 🛠️ CLI Tools
 
-### Batch Updates
-Group multiple state updates together to prevent unnecessary re-renders:
+Frontend Hamroun includes a powerful CLI for scaffolding projects, components, and API routes:
 
-```jsx
-import { batchUpdates } from 'frontend-hamroun';
-
-function handleSubmit() {
-  batchUpdates(() => {
-    setSubmitting(true);
-    setFormData({ name: '', email: '' });
-    setErrors({});
-    setSubmitCount(c => c + 1);
-  });
-}
+<details>
+<summary><b>Project Creation</b></summary>
+
+```bash
+# Create a new project with interactive prompts
+npx frontend-hamroun create my-app
+
+# Create with specific template
+npx frontend-hamroun create my-app --template fullstack-app
 ```
 
-## CLI Tools
+Available templates:
+- `basic-app`: Minimal client-side setup
+- `ssr-template`: Server-side rendering with hydration
+- `fullstack-app`: Complete solution with frontend, backend, auth, and DB
+</details>
 
-Frontend Hamroun includes powerful CLI tools for development:
+<details>
+<summary><b>Component Generation</b></summary>
 
 ```bash
-# Create a new project
-npx frontend-hamroun create my-app
-
 # Generate a new component
 npx frontend-hamroun add:component Button
 
-# Create a new page
-npx frontend-hamroun add:page Home
+# Generate a TypeScript component
+npx frontend-hamroun add:component UserProfile --typescript
 
-# Generate an API route
-npx frontend-hamroun add:api users --methods=get,post,put,delete
+# Specify path and hooks
+npx frontend-hamroun add:component Sidebar --path=src/layout --hooks=useState,useEffect
 ```
+</details>
 
-## Project Templates
+<details>
+<summary><b>API Route Generation</b></summary>
 
-Choose from multiple project templates:
+```bash
+# Generate API route
+npx frontend-hamroun add:api products
+
+# Specify HTTP methods and auth requirement
+npx frontend-hamroun add:api orders --methods=get,post --auth
+```
+</details>
+
+## 🧩 Advanced Usage
+
+<details>
+<summary><b>Custom Hooks</b></summary>
 
-1. **Basic App**: Client-side SPA with essential features
-2. **SSR Template**: Server-side rendering with hydration
-3. **Fullstack App**: Complete solution with API, authentication, and database
+```jsx
+import { useState, useEffect } from 'frontend-hamroun';
+
+// Custom hook for fetching data
+function useFetch(url, options = {}) {
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+  
+  useEffect(() => {
+    setLoading(true);
+    setError(null);
+    
+    fetch(url, options)
+      .then(response => {
+        if (!response.ok) {
+          throw new Error(`HTTP error ${response.status}`);
+        }
+        return response.json();
+      })
+      .then(json => {
+        setData(json);
+        setLoading(false);
+      })
+      .catch(err => {
+        setError(err.message);
+        setLoading(false);
+      });
+  }, [url]);
+  
+  return { data, loading, error };
+}
+
+// Usage
+function UserList() {
+  const { data, loading, error } = useFetch('/api/users');
+  
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error}</div>;
+  
+  return (
+    <ul>
+      {data.map(user => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+</details>
 
-## TypeScript Support
+<details>
+<summary><b>Performance Optimization Techniques</b></summary>
+
+```jsx
+import { useMemo, useState, useRef, batchUpdates } from 'frontend-hamroun';
+
+function OptimizedList({ items }) {
+  const [filter, setFilter] = useState('');
+  const [sortOrder, setSortOrder] = useState('asc');
+  const prevItems = useRef(items);
+  
+  // Memoize expensive calculations
+  const processedItems = useMemo(() => {
+    console.log('Processing items...');
+    let result = [...items];
+    
+    // Apply filter
+    if (filter) {
+      result = result.filter(item => 
+        item.name.toLowerCase().includes(filter.toLowerCase())
+      );
+    }
+    
+    // Apply sorting
+    result.sort((a, b) => {
+      const comparison = a.name.localeCompare(b.name);
+      return sortOrder === 'asc' ? comparison : -comparison;
+    });
+    
+    return result;
+  }, [items, filter, sortOrder]);
+  
+  // Check for changed items with more control than dependency arrays
+  if (items !== prevItems.current) {
+    console.log('Items array reference changed');
+    prevItems.current = items;
+  }
+  
+  // Batch multiple state updates together
+  const toggleSortAndClear = () => {
+    batchUpdates(() => {
+      setSortOrder(sortOrder === 'asc' ? 'desc' : 'asc');
+      setFilter('');
+    });
+  };
+  
+  return (
+    <div>
+      <div>
+        <input 
+          type="text"
+          value={filter}
+          onChange={e => setFilter(e.target.value)}
+          placeholder="Filter items..."
+        />
+        <button onClick={toggleSortAndClear}>
+          Toggle Sort ({sortOrder})
+        </button>
+      </div>
+      
+      {/* Using key for efficient list rendering */}
+      <ul>
+        {processedItems.map(item => (
+          <li key={item.id}>{item.name}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+</details>
+
+## 📝 TypeScript Support
+
+Frontend Hamroun is built with TypeScript and comes with complete type definitions:
+
+<details>
+<summary><b>Type-Safe Component Example</b></summary>
 
 ```tsx
-import { useState } from 'frontend-hamroun';
+import { useState, useEffect } from 'frontend-hamroun';
 
-interface UserProps {
+// Define props interface
+interface UserProfileProps {
   id: number;
   name: string;
   email: string;
+  role: 'admin' | 'user' | 'guest';
+  onStatusChange?: (id: number, active: boolean) => void;
+}
+
+// Define state interface
+interface UserProfileState {
+  isActive: boolean;
+  isEditing: boolean;
+  formData: {
+    name: string;
+    email: string;
+  };
 }
 
-function UserProfile({ id, name, email }: UserProps) {
-  const [isEditing, setEditing] = useState(false);
+function UserProfile({ 
+  id, 
+  name, 
+  email, 
+  role, 
+  onStatusChange 
+}: UserProfileProps) {
+  // Type-safe state
+  const [state, setState] = useState<UserProfileState>({
+    isActive: true,
+    isEditing: false,
+    formData: {
+      name,
+      email
+    }
+  });
+  
+  // Type-safe event handlers
+  const toggleStatus = (): void => {
+    const newStatus = !state.isActive;
+    setState(prev => ({
+      ...prev,
+      isActive: newStatus
+    }));
+    
+    if (onStatusChange) {
+      onStatusChange(id, newStatus);
+    }
+  };
+  
+  // Type-safe refs
+  const formRef = useRef<HTMLFormElement>(null);
   
   return (
     <div className="user-profile">
       <h2>{name}</h2>
-      <p>{email}</p>
-      <button onClick={() => setEditing(!isEditing)}>
-        {isEditing ? 'Cancel' : 'Edit'}
+      <p>Email: {email}</p>
+      <p>Role: {role}</p>
+      <p>Status: {state.isActive ? 'Active' : 'Inactive'}</p>
+      
+      <button onClick={toggleStatus}>
+        {state.isActive ? 'Deactivate' : 'Activate'}
       </button>
+      
+      {state.isEditing ? (
+        <form ref={formRef}>
+          {/* Form fields */}
+        </form>
+      ) : (
+        <button onClick={() => setState(prev => ({ 
+          ...prev, 
+          isEditing: true 
+        }))}>
+          Edit
+        </button>
+      )}
     </div>
   );
 }
+
+// Usage with type checking
+const App = () => (
+  <div>
+    <UserProfile
+      id={1}
+      name="John Doe"
+      email="john@example.com"
+      role="admin"
+      onStatusChange={(id, active) => {
+        console.log(`User ${id} status changed to ${active}`);
+      }}
+    />
+    
+    {/* This would cause TypeScript errors */}
+    {/* 
+    <UserProfile 
+      id="1"          // Error: string is not assignable to number
+      name="Jane Doe" 
+      role="manager"  // Error: 'manager' is not assignable
+    /> 
+    */}
+  </div>
+);
 ```
+</details>
 
-## Browser Compatibility
+<details>
+<summary><b>Type-Safe API Routes</b></summary>
 
-Frontend Hamroun works in all modern browsers (Chrome, Firefox, Safari, Edge) and in IE11 with appropriate polyfills.
+```ts
+// types.ts
+export interface User {
+  id?: string;
+  name: string;
+  email: string;
+  password?: string;
+  role: 'admin' | 'user';
+  createdAt?: Date;
+  updatedAt?: Date;
+}
 
-## Documentation
+// api/users/[id].ts
+import type { User } from '../../types';
 
-For complete documentation, visit our [GitHub repository](https://github.com/hamroun/frontend-hamroun).
+export async function get(req, res) {
+  const { id } = req.params;
+  
+  try {
+    const user = await req.db.collection('users').findOne({ 
+      _id: new ObjectId(id) 
+    }) as User;
+    
+    if (!user) {
+      return res.status(404).json({ error: 'User not found' });
+    }
+    
+    // Omit sensitive data
+    const { password, ...safeUser } = user;
+    
+    res.json(safeUser);
+  } catch (error) {
+    res.status(500).json({ error: 'Server error' });
+  }
+}
 
-## License
+export async function put(req, res) {
+  const { id } = req.params;
+  const { name, email, role } = req.body as Partial<User>;
+  
+  // Validate that role is a valid enum value
+  if (role && !['admin', 'user'].includes(role)) {
+    return res.status(400).json({ error: 'Invalid role' });
+  }
+  
+  try {
+    await req.db.collection('users').updateOne(
+      { _id: new ObjectId(id) },
+      { 
+        $set: { 
+          ...(name && { name }),
+          ...(email && { email }),
+          ...(role && { role }),
+          updatedAt: new Date()
+        } 
+      }
+    );
+    
+    res.json({ success: true });
+  } catch (error) {
+    res.status(500).json({ error: 'Server error' });
+  }
+}
+```
+</details>
+
+## 🌐 Browser Compatibility
+
+Frontend Hamroun supports all modern browsers out of the box:
+
+- Chrome (latest 2 versions)
+- Firefox (latest 2 versions)
+- Safari (latest 2 versions)
+- Edge (latest 2 versions)
+
+For older browsers like IE11, you'll need:
+- Appropriate polyfills
+- Transpilation to ES5
+- CSS compatibility work
+
+## ❓ Frequently Asked Questions
+
+<details>
+<summary><b>How does Frontend Hamroun compare to React?</b></summary>
+
+Frontend Hamroun offers a React-like API but with additional built-in features:
+- Smaller bundle size (~5KB vs. 42KB+)
+- Integrated backend capabilities
+- Built-in server-side rendering
+- Database integrations
+- Authentication system
+
+For React developers, the learning curve is minimal.
+</details>
+
+<details>
+<summary><b>Can I use it with existing React components?</b></summary>
+
+While Frontend Hamroun's API is similar to React's, they have different internal implementations. You can:
+- Port React components to Frontend Hamroun with minimal changes
+- Use React components in dedicated sections with a compatibility layer
+- Share non-UI code and logic between both frameworks
+</details>
+
+<details>
+<summary><b>Does it support static site generation (SSG)?</b></summary>
+
+Yes, Frontend Hamroun provides tools for static site generation. Use the `renderToString` API to pre-render pages at build time.
+</details>
+
+## 📄 License
 
 MIT © Hamroun
+
+---
+
+<p align="center">
+  <a href="#-table-of-contents">⬆️ Back to top</a>
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontend-hamroun",
-  "version": "1.2.63",
+  "version": "1.2.65",
   "description": "A lightweight full-stack JavaScript framework",
   "type": "module",
   "main": "./dist/index.js",