create-aziz-app 2.0.15 → 3.0.0

package/template/docs/STYLING.md

@@ -1,269 +0,0 @@
-# Styling Guide
-
-## Overview
-
-Aziz App uses external CSS files instead of inline styles for better organization and maintainability.
-
-## File Structure
-
-```
-styles/
-├── globals.css      ← Default custom CSS
-└── tailwind.css     ← Tailwind CSS (when selected)
-```
-
-## globals.css
-
-The default stylesheet that includes:
-- CSS Reset
-- Base body styles
-- Navbar and Footer styles
-- Card, Button, Form components
-- Typography styles
-- Utility classes
-
-### Usage
-
-```html
-<!-- Already included in app.html -->
-<link rel="stylesheet" href="styles/globals.css">
-```
-
-### Available Classes
-
-**Layout:**
-- `.card` - White card with shadow
-- `#root` - Main content wrapper
-
-**Buttons:**
-- `.btn` - Base button style
-- `.btn-primary` - Primary button (blue)
-- `.btn-danger` - Danger button (red)
-- `.btn-grey` - Grey button
-
-**Counter:**
-- `.count-display` - Large number display
-- `.counter-actions` - Button group
-
-**Forms:**
-- `input`, `textarea` - Styled form inputs
-- `form` - Flex column layout
-
-**404:**
-- `.not-found` - Centered 404 page
-
-## tailwind.css
-
-When using Tailwind CSS, this file provides:
-- Tailwind directives (@tailwind base, components, utilities)
-- Custom component classes
-- Custom utility classes
-- Theme extensions
-
-### Custom Colors
-
-```css
-.text-primary { color: #61dafb; }
-.bg-primary { background-color: #61dafb; }
-.text-dark { color: #282c34; }
-.bg-dark { background-color: #282c34; }
-```
-
-### Custom Components
-
-All the same classes from globals.css are available as Tailwind components:
-- `.card`
-- `.btn`, `.btn-primary`, `.btn-danger`, `.btn-grey`
-- `.count-display`
-- `.counter-actions`
-
-## Customizing Styles
-
-### Modify globals.css
-
-Edit `styles/globals.css` to change:
-- Colors
-- Spacing
-- Typography
-- Component styles
-
-```css
-/* Example: Change primary color */
-nav .brand {
-    color: #your-color;
-}
-
-.btn-primary {
-    background-color: #your-color;
-}
-```
-
-### Modify tailwind.css
-
-Edit `styles/tailwind.css` to:
-- Add custom components
-- Add custom utilities
-- Modify theme
-
-```css
-@layer components {
-    .my-custom-card {
-        @apply bg-white p-6 rounded-lg shadow-xl;
-    }
-}
-```
-
-### Add New CSS Files
-
-1. Create a new CSS file in `styles/`
-2. Link it in `app.html`:
-
-```html
-<link rel="stylesheet" href="styles/my-custom.css">
-```
-
-## Best Practices
-
-### Organization
-- Keep global styles in `globals.css`
-- Create separate files for large features
-- Use meaningful class names
-
-### Performance
-- Minimize CSS file size
-- Avoid deep nesting
-- Use CSS variables for themes
-
-### Maintainability
-- Comment complex styles
-- Group related styles
-- Use consistent naming
-
-## Responsive Design
-
-### Custom CSS
-
-```css
-/* Mobile first approach */
-.card {
-    padding: 16px;
-}
-
-/* Tablet and up */
-@media (min-width: 768px) {
-    .card {
-        padding: 24px;
-    }
-}
-```
-
-### Tailwind CSS
-
-```javascript
-// Use responsive prefixes
-<div class="p-4 md:p-6 lg:p-8">
-    Responsive padding
-</div>
-```
-
-## Dark Mode
-
-### Custom CSS
-
-```css
-/* Add dark mode support */
-@media (prefers-color-scheme: dark) {
-    body {
-        background-color: #1a1a1a;
-        color: #f5f5f5;
-    }
-    
-    .card {
-        background-color: #2a2a2a;
-    }
-}
-```
-
-### Tailwind CSS
-
-```javascript
-// Use dark: prefix
-<div class="bg-white dark:bg-gray-800">
-    Dark mode support
-</div>
-```
-
-## CSS Variables
-
-### Define Variables
-
-```css
-:root {
-    --primary-color: #61dafb;
-    --dark-color: #282c34;
-    --spacing: 16px;
-}
-```
-
-### Use Variables
-
-```css
-.btn-primary {
-    background-color: var(--primary-color);
-    padding: var(--spacing);
-}
-```
-
-## Tips
-
-1. **Start Simple** - Use the provided classes first
-2. **Be Consistent** - Stick to one naming convention
-3. **Mobile First** - Design for mobile, enhance for desktop
-4. **Test Browsers** - Check in different browsers
-5. **Optimize** - Remove unused styles
-
-## Examples
-
-### Custom Button
-
-```css
-/* In globals.css */
-.btn-success {
-    background-color: #28a745;
-    color: white;
-    padding: 10px 22px;
-    border-radius: 8px;
-    border: none;
-    cursor: pointer;
-}
-```
-
-```javascript
-// In your component
-<button class="btn-success">Success!</button>
-```
-
-### Custom Card
-
-```css
-/* In globals.css */
-.card-highlight {
-    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-    color: white;
-    padding: 24px;
-    border-radius: 10px;
-}
-```
-
-```javascript
-// In your component
-<div class="card-highlight">
-    <h2>Highlighted Card</h2>
-</div>
-```
-
-## Resources
-
-- [MDN CSS Reference](https://developer.mozilla.org/en-US/docs/Web/CSS)
-- [CSS Tricks](https://css-tricks.com/)
-- [Can I Use](https://caniuse.com/) - Browser compatibility

package/template/docs/TROUBLESHOOTING.md

@@ -1,282 +0,0 @@
-# Troubleshooting Guide
-
-## Live Reload Issues
-
-### Indicator Stuck on "Connecting..."
-
-**Symptoms:**
-- Green indicator shows "🔌 Connecting..." and never changes
-- Changes don't show without hard refresh (Ctrl+Shift+R)
-
-**Causes:**
-- Browser cached old version of `app.html` without live reload script
-- SSE connection blocked by browser extension or firewall
-
-**Solutions:**
-
-1. **Hard refresh once** to clear cache:
-   - Windows/Linux: `Ctrl + Shift + R`
-   - Mac: `Cmd + Shift + R`
-
-2. **Check browser console** (F12):
-   - Look for: `"🔌 Connecting to live reload at http://localhost:3000/live-reload"`
-   - Look for: `"✅ Live reload connected"`
-   - If you see errors, note them
-
-3. **Disable browser extensions** temporarily:
-   - Ad blockers can block SSE connections
-   - Try in incognito/private mode
-
-4. **Check terminal output**:
-   - Should show: `"🔌 [time] Browser connected for live reload (1 total)"`
-   - If not showing, SSE connection failed
-
-5. **Restart dev server**:
-   ```bash
-   # Stop with Ctrl+C
-   npm run dev
-   ```
-
-6. **Clear browser cache completely**:
-   - Chrome: Settings → Privacy → Clear browsing data
-   - Firefox: Settings → Privacy → Clear Data
-   - Edge: Settings → Privacy → Clear browsing data
-
-### Changes Not Showing
-
-**Symptoms:**
-- Indicator shows "✅ Live Reload Active"
-- Page reloads but changes don't appear
-
-**Solutions:**
-
-1. **Check file was saved**:
-   - Verify file has no unsaved indicator in editor
-   - Check terminal shows: `"📝 Detected change: pages/Home.jsx"`
-
-2. **Check imports were regenerated**:
-   - Terminal should show: `"🔄 Regenerating imports..."`
-   - Check `app.html` has your file listed
-
-3. **Verify file location**:
-   - Files must be in: `api/`, `components/`, `pages/`, `modules/`, or `styles/`
-   - Files outside these folders won't trigger reload
-
-4. **Check for JavaScript errors**:
-   - Open browser console (F12)
-   - Look for red error messages
-   - Fix any syntax errors in your code
-
-5. **Manual import regeneration**:
-   ```bash
-   npm run build
-   ```
-
-### Indicator Shows "❌ Connection Error"
-
-**Symptoms:**
-- Red indicator with error message
-- Console shows EventSource errors
-
-**Solutions:**
-
-1. **Check dev server is running**:
-   - Terminal should show: `"✅ Dev server running with live reload!"`
-   - If not, run: `npm run dev`
-
-2. **Check port is correct**:
-   - Browser URL should match terminal output
-   - Example: `http://localhost:3000/`
-
-3. **Firewall blocking connection**:
-   - Allow Node.js through firewall
-   - Try different port: `PORT=3001 npm run dev`
-
-4. **Browser doesn't support EventSource**:
-   - Update to latest browser version
-   - Try different browser (Chrome, Firefox, Edge)
-
-## Page Not Found (404)
-
-**Symptoms:**
-- Clicking link shows 404 page
-- URL is correct but page doesn't load
-
-**Solutions:**
-
-1. **Check function name**:
-   ```jsx
-   // ✅ Correct - ends with "Page"
-   function AboutPage() { }
-   
-   // ❌ Wrong - missing "Page"
-   function About() { }
-   ```
-
-2. **Check file is loaded**:
-   - Open `app.html`
-   - Look for: `<script type="text/babel" src="pages/YourPage.jsx"></script>`
-   - If missing, run: `npm run build`
-
-3. **Check browser console**:
-   - Look for: `"📄 Auto-registered: about → AboutPage()"`
-   - If missing, function name is wrong
-
-4. **Manual registration**:
-   ```jsx
-   // Add this if auto-registration fails
-   registerPage("about", AboutPage);
-   ```
-
-## State Not Working
-
-**Symptoms:**
-- `useState` is undefined
-- State doesn't update
-
-**Solutions:**
-
-1. **Check `/** @jsx h */` at top of file**:
-   ```jsx
-   /** @jsx h */
-   
-   function MyPage() {
-       const [count, setCount] = useState(0);
-       // ...
-   }
-   ```
-
-2. **Check state.js is loaded**:
-   - Open `app.html`
-   - Look for: `<script type="text/babel" src="modules/state.js"></script>`
-
-3. **Check browser console for errors**:
-   - Look for: `"useState is not defined"`
-   - If found, state.js didn't load
-
-## Styling Not Applied
-
-**Symptoms:**
-- Page has no styling
-- Looks like plain HTML
-
-**Solutions:**
-
-1. **Check CSS file is linked**:
-   - Open `app.html`
-   - Look for: `<link rel="stylesheet" href="styles/globals.css">`
-
-2. **Check CSS file exists**:
-   - Verify `styles/globals.css` exists
-   - Check file has content
-
-3. **Check class names**:
-   ```jsx
-   // ✅ Correct
-   <div class="card">
-   
-   // ❌ Wrong (React syntax)
-   <div className="card">
-   ```
-
-4. **Hard refresh**:
-   - CSS might be cached
-   - Press: `Ctrl + Shift + R` (Windows) or `Cmd + Shift + R` (Mac)
-
-## API Routes Not Working
-
-**Symptoms:**
-- `fetchApi()` returns 404
-- API endpoint not found
-
-**Solutions:**
-
-1. **Check API file is loaded**:
-   - Open `app.html`
-   - Look for: `<script type="text/babel" src="api/yourfile.js"></script>`
-
-2. **Check route registration**:
-   ```jsx
-   // In api/users.js
-   registerApiRoute('users', async (req, res) => {
-       // handler
-   });
-   ```
-
-3. **Check URL format**:
-   ```jsx
-   // ✅ Correct
-   await fetchApi('/api/users');
-   
-   // ❌ Wrong
-   await fetchApi('api/users');  // missing leading /
-   await fetchApi('/users');     // missing /api/
-   ```
-
-4. **Check browser console**:
-   - Look for network errors
-   - Check request URL is correct
-
-## Port Already in Use
-
-**Symptoms:**
-- Error: `EADDRINUSE: address already in use :::3000`
-
-**Solutions:**
-
-1. **Server auto-finds next port**:
-   - Check terminal for actual port
-   - Example: `"Server running at http://localhost:3001/"`
-
-2. **Kill process on port 3000**:
-   ```bash
-   # Windows
-   netstat -ano | findstr :3000
-   taskkill /PID <PID> /F
-   
-   # Mac/Linux
-   lsof -ti:3000 | xargs kill -9
-   ```
-
-3. **Use different port**:
-   ```bash
-   PORT=3001 npm run dev
-   ```
-
-## General Tips
-
-### Before Asking for Help
-
-1. **Check browser console** (F12) for errors
-2. **Check terminal output** for server errors
-3. **Try hard refresh** (Ctrl+Shift+R)
-4. **Try incognito mode** to rule out extensions
-5. **Restart dev server** (Ctrl+C, then `npm run dev`)
-
-### Debug Checklist
-
-- [ ] Dev server is running
-- [ ] Browser URL matches server URL
-- [ ] File is saved
-- [ ] File is in correct folder
-- [ ] `/** @jsx h */` at top of JSX files
-- [ ] Function name ends with "Page"
-- [ ] No JavaScript errors in console
-- [ ] Live reload indicator is green
-
-### Still Having Issues?
-
-1. **Check documentation**:
-   - [Getting Started](GETTING-STARTED.md)
-   - [Auto-Registration](AUTO-REGISTRATION.md)
-   - [Dev Server](DEV-SERVER.md)
-
-2. **Create minimal reproduction**:
-   - Create new app: `npx create-aziz-app test-app`
-   - Test if issue persists in fresh app
-
-3. **Report issue** with:
-   - Browser console output
-   - Terminal output
-   - Code that's not working
-   - Steps to reproduce

package/template/modules/README.md

@@ -1,129 +0,0 @@
-# Modules Folder
-
-This folder contains the core system modules that power your application.
-
-## Core Modules
-
-### 📦 router.js
-The main application engine containing:
-- **`h()` function** - JSX createElement (converts JSX to DOM elements)
-- **Router system** - File-based routing with hash navigation
-- **`registerPage()`** - Register page components
-- **`navigate()`** - Navigate between pages
-- **`renderPage()`** - Render engine with focus preservation
-- **Global state** - Basic global state management
-
-### 🔄 state.js
-State management system:
-- **`useState(initialValue)`** - React-like hooks for local component state
-- **Hook system** - Manages state across re-renders
-- **`resetHooks()`** - Resets hook index before each render
-
-### 🌐 api.js
-API route system (Next.js-like):
-- **`registerApiRoute(path, handler)`** - Register API endpoints
-- **`fetchApi(path, options)`** - Fetch-like API for making requests
-- **Request/Response objects** - Express-like req/res handling
-- **Mock API system** - Client-side API simulation
-
-## How It Works
-
-### 1. Router System
-```javascript
-// Register a page
-registerPage("home", HomePage);
-
-// Navigate programmatically
-navigate("about");
-
-// Get current path
-const path = getCurrentPath(); // returns "home", "about", etc.
-```
-
-### 2. State Management
-```javascript
-// Use state in components
-const [count, setCount] = useState(0);
-const [name, setName] = useState('');
-
-// Update state
-setCount(count + 1);
-setName('New Name');
-```
-
-### 3. API Routes
-```javascript
-// Register an API route
-registerApiRoute('myroute', async (req, res) => {
-    return res.status(200).json({ data: 'Hello!' });
-});
-
-// Call from components
-const response = await fetchApi('/api/myroute');
-const data = await response.json();
-```
-
-## Module Loading Order
-
-The modules must be loaded in this order (see `app.html`):
-
-1. **router.js** - Core engine and routing
-2. **state.js** - State management
-3. **api.js** - API system
-4. **API routes** - Your API endpoints
-5. **Components** - Reusable UI components
-6. **Pages** - Page components
-7. **Start app** - Call `startApp()`
-
-## Extending the System
-
-### Add New Core Features
-
-Create new modules in this folder for additional core functionality:
-
-```javascript
-// modules/auth.js
-function login(username, password) {
-    // Authentication logic
-}
-
-function logout() {
-    // Logout logic
-}
-
-window.auth = { login, logout };
-```
-
-Then load it in `app.html`:
-```html
-<script type="text/babel" src="modules/auth.js"></script>
-```
-
-### Module Best Practices
-
-1. **Export to global scope** - Use `window.functionName` or `globalThis.functionName`
-2. **Keep modules focused** - Each module should have a single responsibility
-3. **Document your modules** - Add comments explaining what each function does
-4. **Load order matters** - Ensure dependencies are loaded first
-
-## File Structure
-
-```
-template/
-├── modules/           # Core system modules (you are here)
-│   ├── router.js     # Routing and rendering engine
-│   ├── state.js      # State management
-│   ├── api.js        # API route system
-│   └── README.md     # This file
-├── api/              # API route handlers
-├── components/       # Reusable UI components
-├── pages/            # Page components
-└── app.html          # Main HTML file
-```
-
-## Notes
-
-- These modules are loaded via Babel standalone for JSX support
-- All modules use the `/** @jsx h */` pragma to use the custom `h()` function
-- The system is designed to be simple and easy to understand
-- You can replace any module with your own implementation

package/template/modules/api.js

@@ -1,44 +0,0 @@
-/** @jsx h */
-
-// ============================================================
-//  API CLIENT
-//  Fetch-like API for making requests to backend API routes
-//  API routes run on the SERVER (Node.js), not in the browser
-// ============================================================
-
-// Fetch-like API for making requests to backend
-async function fetchApi(path, options = {}) {
-    const {
-        method = 'GET',
-        body = null,
-        headers = {}
-    } = options;
-
-    const fetchOptions = {
-        method,
-        headers: {
-            'Content-Type': 'application/json',
-            ...headers
-        }
-    };
-
-    if (body) {
-        fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
-    }
-
-    try {
-        const response = await fetch(path, fetchOptions);
-        return response;
-    } catch (error) {
-        console.error('API Error:', error);
-        throw error;
-    }
-}
-
-// Export to global scope
-window.fetchApi = fetchApi;
-
-// Also make available without window prefix
-if (typeof globalThis !== 'undefined') {
-    globalThis.fetchApi = fetchApi;
-}