create-aziz-app 2.0.14 → 3.0.0

package/template/docs/AUTO-REGISTRATION.md

@@ -1,248 +0,0 @@
-# Auto-Registration Guide
-
-## Overview
-
-Pages automatically register themselves based on their function name. No need to call `registerPage()` manually!
-
-## How It Works
-
-### ✨ Automatic Registration
-
-Just name your page function with "Page" at the end:
-
-```jsx
-/** @jsx h */
-
-// That's it! Automatically becomes route "#/example"
-function ExamplePage() {
-    return (
-        <div>
-            <h1>Example Page</h1>
-            <p>This page auto-registered!</p>
-        </div>
-    );
-}
-```
-
-### Function Name → Route Mapping
-
-The system converts your function name to a route:
-
-| Function Name | Auto Route | URL |
-|--------------|------------|-----|
-| `HomePage()` | `home` | `#/home` |
-| `AboutPage()` | `about` | `#/about` |
-| `ContactPage()` | `contact` | `#/contact` |
-| `UserProfilePage()` | `userprofile` | `#/userprofile` |
-| `MyAwesomePage()` | `myawesome` | `#/myawesome` |
-
-**Rule:** Remove "Page" suffix and convert to lowercase.
-
-## Manual Registration (Optional)
-
-You can still manually register for custom route names:
-
-```jsx
-/** @jsx h */
-
-// Custom route name with dashes or different naming
-registerPage("user-profile", UserProfilePage);
-
-function UserProfilePage() {
-    return <div><h1>User Profile</h1></div>;
-}
-```
-
-### When to Use Manual Registration
-
-- **Custom route names** with dashes: `"api-demo"`, `"user-settings"`
-- **Multiple routes** pointing to same component
-- **Override auto-registration** with different name
-
-## Examples
-
-### Example 1: Simple Auto Page
-
-```jsx
-/** @jsx h */
-
-function ProductsPage() {
-    return (
-        <div>
-            <h1>Products</h1>
-            <p>Browse our products</p>
-        </div>
-    );
-}
-```
-
-Access at: `#/products`
-
-### Example 2: With State
-
-```jsx
-/** @jsx h */
-
-function DashboardPage() {
-    const [count, setCount] = useState(0);
-    
-    return (
-        <div>
-            <h1>Dashboard</h1>
-            <p>Count: {count}</p>
-            <button onClick={() => setCount(count + 1)}>
-                Increment
-            </button>
-        </div>
-    );
-}
-```
-
-Access at: `#/dashboard`
-
-### Example 3: Manual Registration
-
-```jsx
-/** @jsx h */
-
-// Want route "#/user-settings" instead of "#/usersettings"
-registerPage("user-settings", UserSettingsPage);
-
-function UserSettingsPage() {
-    return (
-        <div>
-            <h1>User Settings</h1>
-        </div>
-    );
-}
-```
-
-Access at: `#/user-settings`
-
-## Creating a New Page
-
-### Step 1: Create the file
-
-Create `pages/MyNewPage.jsx`:
-
-```jsx
-/** @jsx h */
-
-function MyNewPage() {
-    return (
-        <div>
-            <h1>My New Page</h1>
-            <div class="card">
-                <p>This is my new page!</p>
-            </div>
-        </div>
-    );
-}
-```
-
-### Step 2: That's it!
-
-The dev server will:
-1. Detect the new file
-2. Auto-generate the import in `app.html`
-3. Auto-register the route as `#/mynew`
-4. Reload the browser
-
-Navigate to `#/mynew` and your page appears!
-
-## Debugging
-
-### Check Auto-Registration
-
-Open browser console when the app starts. You'll see:
-
-```
-📄 Auto-registered: home → HomePage()
-📄 Auto-registered: about → AboutPage()
-📄 Auto-registered: contact → ContactPage()
-📄 Auto-registered: mynew → MyNewPage()
-```
-
-### Page Not Found?
-
-1. **Check function name** - Must end with "Page"
-2. **Check file is loaded** - Look in `app.html` for the script tag
-3. **Check console** - Look for auto-registration message
-4. **Try manual registration** - Use `registerPage("route", ComponentPage)`
-
-## Best Practices
-
-### ✅ Do This
-
-```jsx
-// Clear, descriptive names
-function HomePage() { }
-function AboutPage() { }
-function ContactPage() { }
-function UserProfilePage() { }
-```
-
-### ❌ Avoid This
-
-```jsx
-// Won't auto-register (missing "Page" suffix)
-function Home() { }
-function About() { }
-
-// Will create weird routes
-function Page() { }  // route: "" (empty)
-function MyPage() { } // route: "my" (too generic)
-```
-
-## Migration Guide
-
-### Old Way (Still Works)
-
-```jsx
-/** @jsx h */
-
-registerPage("about", AboutPage);
-
-function AboutPage() {
-    return <div><h1>About</h1></div>;
-}
-```
-
-### New Way (Simpler)
-
-```jsx
-/** @jsx h */
-
-function AboutPage() {
-    return <div><h1>About</h1></div>;
-}
-```
-
-Both work! The new way is just less code.
-
-## Advanced: Multiple Routes
-
-Point multiple routes to the same component:
-
-```jsx
-/** @jsx h */
-
-// Auto-registers as "dashboard"
-function DashboardPage() {
-    return <div><h1>Dashboard</h1></div>;
-}
-
-// Also register as "home" and "index"
-registerPage("home", DashboardPage);
-registerPage("index", DashboardPage);
-```
-
-Now `#/dashboard`, `#/home`, and `#/index` all show the same page!
-
-## Summary
-
-- **Function name ends with "Page"** → Auto-registers
-- **Route name** = function name without "Page", lowercase
-- **Manual registration** still available for custom names
-- **Dev server** handles everything automatically
-- **Zero configuration** needed for basic pages

package/template/docs/CSS-FRAMEWORKS.md

@@ -1,221 +0,0 @@
-# CSS Frameworks Guide
-
-## Overview
-
-Aziz App supports three CSS options:
-1. **Custom CSS** - Built-in custom styles
-2. **Bootstrap 5** - Popular component framework
-3. **Tailwind CSS** - Utility-first framework
-
-## Bootstrap 5
-
-### What's Included
-
-When you choose Bootstrap, the CLI automatically adds:
-- Bootstrap 5.3.2 CSS (CDN)
-- Bootstrap Icons
-- Bootstrap 5 JS Bundle
-- Updated Navbar with Bootstrap classes
-- Updated Footer with Bootstrap classes
-
-### Using Bootstrap
-
-```javascript
-// Example: Bootstrap Button
-<button class="btn btn-primary">Click Me</button>
-
-// Example: Bootstrap Card
-<div class="card">
-    <div class="card-body">
-        <h5 class="card-title">Card Title</h5>
-        <p class="card-text">Some content</p>
-    </div>
-</div>
-
-// Example: Bootstrap Grid
-<div class="container">
-    <div class="row">
-        <div class="col-md-6">Column 1</div>
-        <div class="col-md-6">Column 2</div>
-    </div>
-</div>
-```
-
-### Bootstrap Components
-
-Available components:
-- Buttons, Cards, Modals
-- Forms, Inputs, Validation
-- Navbar, Dropdowns, Tabs
-- Alerts, Badges, Progress bars
-- Grid system, Flexbox utilities
-
-### Resources
-
-- [Bootstrap Docs](https://getbootstrap.com/docs/5.3/)
-- [Bootstrap Icons](https://icons.getbootstrap.com/)
-- [Bootstrap Examples](https://getbootstrap.com/docs/5.3/examples/)
-
-## Tailwind CSS
-
-### What's Included
-
-When you choose Tailwind, the CLI automatically adds:
-- Tailwind CSS CDN (Play CDN)
-- Custom color configuration
-- Updated Navbar with Tailwind classes
-- Updated Footer with Tailwind classes
-
-### Using Tailwind
-
-```javascript
-// Example: Tailwind Button
-<button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
-    Click Me
-</button>
-
-// Example: Tailwind Card
-<div class="bg-white shadow-lg rounded-lg p-6">
-    <h2 class="text-2xl font-bold mb-4">Card Title</h2>
-    <p class="text-gray-700">Some content</p>
-</div>
-
-// Example: Tailwind Grid
-<div class="container mx-auto">
-    <div class="grid grid-cols-2 gap-4">
-        <div>Column 1</div>
-        <div>Column 2</div>
-    </div>
-</div>
-```
-
-### Tailwind Utilities
-
-Common utilities:
-- Layout: `flex`, `grid`, `container`
-- Spacing: `p-4`, `m-2`, `space-x-4`
-- Colors: `bg-blue-500`, `text-red-600`
-- Typography: `text-xl`, `font-bold`
-- Effects: `shadow-lg`, `rounded-lg`
-
-### Custom Colors
-
-Pre-configured colors:
-- `primary` - #61dafb (Aziz blue)
-- `dark` - #282c34 (Dark background)
-
-```javascript
-<div class="bg-primary text-dark">Custom colors!</div>
-```
-
-### Resources
-
-- [Tailwind Docs](https://tailwindcss.com/docs)
-- [Tailwind Cheat Sheet](https://nerdcave.com/tailwind-cheat-sheet)
-- [Tailwind Components](https://tailwindui.com/components)
-
-## Custom CSS
-
-### What's Included
-
-The default custom CSS includes:
-- Reset styles
-- Navbar and Footer styles
-- Card, Button, Form styles
-- Utility classes
-- Responsive design
-
-### Using Custom CSS
-
-```javascript
-// Example: Custom Button
-<button class="btn btn-primary">Click Me</button>
-
-// Example: Custom Card
-<div class="card">
-    <h2>Card Title</h2>
-    <p>Some content</p>
-</div>
-
-// Example: Custom Form
-<form>
-    <input type="text" placeholder="Enter text" />
-    <button class="btn btn-primary">Submit</button>
-</form>
-```
-
-### Available Classes
-
-**Buttons:**
-- `.btn` - Base button
-- `.btn-primary` - Primary button (blue)
-- `.btn-danger` - Danger button (red)
-- `.btn-grey` - Grey button
-
-**Layout:**
-- `.card` - Card container
-- `.count-display` - Large number display
-- `.counter-actions` - Button group
-
-**Forms:**
-- `input`, `textarea` - Styled inputs
-- `form` - Styled form
-
-## Switching Frameworks
-
-### After Project Creation
-
-If you want to switch frameworks after creating your project:
-
-**To Bootstrap:**
-1. Add Bootstrap CDN to `app.html`:
-```html
-<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css" rel="stylesheet">
-<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/js/bootstrap.bundle.min.js"></script>
-```
-
-2. Update your components with Bootstrap classes
-
-**To Tailwind:**
-1. Add Tailwind CDN to `app.html`:
-```html
-<script src="https://cdn.tailwindcss.com"></script>
-```
-
-2. Update your components with Tailwind classes
-
-**To Custom CSS:**
-1. Remove framework CDN links from `app.html`
-2. Update your components with custom classes
-
-## Best Practices
-
-### Bootstrap
-- Use semantic HTML with Bootstrap classes
-- Leverage Bootstrap's grid system
-- Use Bootstrap components for consistency
-- Customize with Bootstrap variables
-
-### Tailwind
-- Use utility classes directly in JSX
-- Combine utilities for complex designs
-- Use responsive prefixes (`md:`, `lg:`)
-- Extract common patterns into components
-
-### Custom CSS
-- Keep styles in `<style>` tag in `app.html`
-- Use BEM naming convention
-- Create reusable utility classes
-- Keep specificity low
-
-## Tips
-
-1. **Consistency** - Stick to one framework per project
-2. **Performance** - CDN links are cached by browsers
-3. **Customization** - All frameworks can be customized
-4. **Learning** - Start with one framework and master it
-5. **Components** - Build reusable components regardless of framework
-
-## Examples
-
-Check the example pages in your project to see the chosen framework in action!

package/template/docs/DEV-SERVER.md

@@ -1,184 +0,0 @@
-# Dev Server Guide
-
-## Overview
-
-The dev server provides a smooth development experience with live reload using WebSocket, automatic import generation, and file watching.
-
-## Features
-
-### 🔄 Live Reload (WebSocket-based)
-- **Automatic browser refresh** when you save files
-- **Visual indicator** in bottom-right corner shows connection status
-- **WebSocket connection** - reliable, fast, no caching issues
-- **CSS hot reload** - instant updates without regenerating imports
-- **Always loaded** - script is part of your HTML, not injected
-
-### 👀 File Watching
-The dev server watches these directories:
-- `api/` - API route files
-- `components/` - React-like components
-- `pages/` - Page components
-- `modules/` - Core system modules
-- `styles/` - CSS files
-
-### 🚀 Auto Import Generation
-- Automatically generates script tags in `app.html`
-- Runs on startup and whenever JS/JSX files change
-- No need to manually add imports
-
-### 🎯 Smart Port Selection
-- Defaults to port 3000
-- Automatically finds next available port if 3000 is busy
-- Shows the actual URL in console
-
-## Usage
-
-```bash
-npm run dev
-```
-
-Then open the URL shown in console (usually `http://localhost:3000/`)
-
-## Visual Indicators
-
-The live reload indicator in the bottom-right corner shows:
-- 🔌 **Connecting...** - Initial connection (gray/green)
-- ✅ **Live Reload** - Connected and watching (green, fades to 30%)
-- 🔄 **Reloading...** - Changes detected, refreshing page (blue)
-- ⚠️ **Disconnected** - Connection lost, attempting to reconnect (orange)
-- ❌ **Offline** - Max reconnection attempts reached (red)
-
-**Click the indicator** to manually reload the page.
-
-Hover over the indicator to make it fully visible.
-
-## How It Works
-
-1. **Server starts** and generates initial imports
-2. **Browser loads** `live-reload-client.js` (always in HTML)
-3. **WebSocket connects** to dev server
-4. **File watcher** detects changes in watched directories
-5. **Debouncing** prevents multiple rapid reloads (300ms for CSS, 500ms for JS)
-6. **Import regeneration** (for JS/JSX changes only)
-7. **WebSocket message** sent to all connected browsers
-8. **Page reload** happens immediately
-
-## Why WebSocket?
-
-Previous versions used Server-Sent Events (SSE) with runtime injection, which had caching issues. The new approach:
-
-- ✅ **Always loaded** - Script is in HTML, not injected at runtime
-- ✅ **No caching issues** - Browser always has the script
-- ✅ **Bidirectional** - WebSocket allows two-way communication
-- ✅ **Reliable** - Built-in reconnection logic
-- ✅ **Fast** - Instant notifications, no polling
-
-## Cache Control
-
-The dev server sends these headers to prevent caching:
-```
-Cache-Control: no-cache, no-store, must-revalidate
-Pragma: no-cache
-Expires: 0
-```
-
-Plus, `app.html` has meta tags:
-```html
-<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">
-<meta http-equiv="Pragma" content="no-cache">
-<meta http-equiv="Expires" content="0">
-```
-
-## Troubleshooting
-
-### Indicator stuck on "Connecting..."?
-
-1. **Check dev server is running** - Terminal should show "✅ Dev server running"
-2. **Check browser console** (F12) - Look for WebSocket errors
-3. **Check port** - Browser URL should match server URL
-4. **Firewall** - Allow Node.js through firewall
-5. **Try different browser** - Rule out browser-specific issues
-
-### Changes not showing?
-
-1. **Check indicator is green** - "✅ Live Reload"
-2. **Check terminal** - Should show "📝 Detected change: ..."
-3. **Check file was saved** - No unsaved indicator in editor
-4. **Check file location** - Must be in watched directories
-5. **Check for errors** - Browser console (F12) for JavaScript errors
-
-### WebSocket connection failed?
-
-1. **Port mismatch** - Check browser URL matches server port
-2. **Proxy/VPN** - May block WebSocket connections
-3. **Browser extension** - Ad blockers can interfere
-4. **Try incognito mode** - Rule out extensions
-
-### Port already in use?
-
-The server automatically tries the next port. Check terminal for actual port:
-```
-🌐 Server running at http://localhost:3001/
-```
-
-## Performance
-
-- **Debouncing** prevents reload spam when saving multiple files
-- **CSS-only changes** skip import regeneration for faster updates
-- **WebSocket** is lightweight and efficient
-- **Multiple browsers** can connect simultaneously
-- **Automatic reconnection** if connection drops
-
-## Development Tips
-
-1. Keep the terminal visible to see file change notifications
-2. The visual indicator helps confirm live reload is working
-3. CSS changes are faster than JS changes (no import regeneration)
-4. Multiple browser tabs will all reload simultaneously
-5. Click the indicator to manually reload if needed
-
-## Production
-
-The live reload script only runs in development (localhost). In production:
-- Script detects non-localhost hostname
-- Exits immediately without connecting
-- No performance impact
-- No visual indicator
-
-## Technical Details
-
-### WebSocket Protocol
-
-The dev server implements a simple WebSocket server without external dependencies:
-- Uses Node.js `http` module's `upgrade` event
-- Performs WebSocket handshake manually
-- Sends text frames to connected clients
-- Handles connection cleanup automatically
-
-### Message Format
-
-Server sends a single message type:
-- `"reload"` - Triggers browser reload
-
-### Reconnection Logic
-
-Client attempts to reconnect:
-- Max 10 attempts
-- 2-second delay between attempts
-- Exponential backoff could be added if needed
-
-## Comparison with Other Tools
-
-| Feature | Aziz App | Live Server | Vite |
-|---------|----------|-------------|------|
-| Setup | Zero config | Zero config | Config file |
-| Speed | Fast | Fast | Very fast |
-| WebSocket | ✅ | ✅ | ✅ |
-| Auto-import | ✅ | ❌ | ✅ |
-| Visual indicator | ✅ | ❌ | ❌ |
-| Dependencies | None | None | Many |
-
-## Summary
-
-The dev server provides a reliable, fast live reload experience using WebSocket. The script is always loaded (not injected), eliminating caching issues. File watching, debouncing, and automatic reconnection make development smooth and efficient.
-