luxaura 1.0.0

package/README.md

@@ -0,0 +1,342 @@
+# Luxaura Framework
+
+> **Intent-Based Full-Stack Web Framework** — build complete apps with `.lux` files.
+
+[![Version](https://img.shields.io/badge/version-1.0.0-6c63ff)](#)
+[![License](https://img.shields.io/badge/license-MIT-green)](#)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](#)
+
+---
+
+## What is Luxaura?
+
+Luxaura is a full-stack web framework where you describe **what** you want — not how to build it. A single `.lux` file contains your UI, state, styles, and backend logic. The compiler handles the rest.
+
+```yaml
+# counter.lux
+
+state
+    count: 0
+
+style
+    self
+        padding: 8
+    Action
+        radius: medium
+        background: #6c63ff
+
+view
+    Box
+        Title "Counter: {count}"
+        Action "Increment"
+            on click:
+                count = count + 1
+```
+
+---
+
+## Installation
+
+```bash
+npm install -g luxaura
+```
+
+Or use it as a project dependency:
+
+```bash
+npm install luxaura
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Create a new project
+luxaura new my-app
+
+# 2. Enter the project
+cd my-app
+
+# 3. Start the dev server (HMR enabled)
+luxaura run
+```
+
+Open `http://localhost:3000` — your app is live.
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `luxaura new <name>` | Create a new project with the full folder structure |
+| `luxaura run` | Start the dev server with Hot Module Replacement |
+| `luxaura build` | Compile for production (splits client/server code) |
+| `luxaura install <lib>` | Install a CSS/JS library (e.g. Tailwind, Bootstrap) |
+| `luxaura generate <type> <name>` | Scaffold a `component`, `page`, or `api` |
+| `luxaura format` | Auto-fix `.lux` file indentation |
+| `luxaura secure` | Scan for XSS, SQL injection, and server-leak risks |
+
+---
+
+## .lux File Anatomy
+
+Every `.lux` file has five blocks:
+
+```yaml
+# 1. PROPS — inputs from parent components
+props
+    title: String
+    count: Number = 0
+
+# 2. STATE — reactive internal data
+state
+    name: "World"
+    active: false
+
+# 3. SERVER — backend logic (Node.js). NEVER sent to browser.
+server
+    import db from "luxaura/db"
+    def saveUser(name):
+        return db.insert("users", { name })
+
+# 4. STYLE — smart properties + CSS
+style
+    self
+        padding: 6
+        shadow: soft
+    Title
+        fontSize: 2xl
+        fontWeight: bold
+
+# 5. VIEW — UI component tree
+view
+    Container
+        Title "{title}"
+        Text "Hello, {name}!"
+        Action "Save"
+            on click:
+                await server.saveUser(name)
+```
+
+---
+
+## Semantic Components
+
+No HTML tags. Use intent-based components:
+
+| Category | Components |
+|---|---|
+| **Layout** | `Box`, `Row`, `Column`, `Grid`, `Container` |
+| **Navigation** | `Nav`, `Sidebar`, `Footer`, `Header` |
+| **Content** | `Title`, `Text`, `Image`, `Icon`, `Badge` |
+| **Interaction** | `Action`, `Input`, `Form`, `Switch`, `Link` |
+| **Data** | `Table`, `List`, `ListItem` |
+| **Overlay** | `Modal`, `Overlay`, `Card` |
+
+---
+
+## Smart Style Properties
+
+```yaml
+style
+    self
+        padding: 4          # → padding: 16px (4 × 4px base)
+        shadow: soft        # → box-shadow: 0 2px 12px rgba(...)
+        radius: large       # → border-radius: 16px
+        fontSize: xl        # → font-size: 1.5rem
+        fontWeight: bold    # → font-weight: 700
+```
+
+Available tokens:
+- **shadow**: `none`, `soft`, `medium`, `hard`
+- **radius**: `none`, `small`, `medium`, `large`, `full`
+- **fontSize**: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`
+- **fontWeight**: `thin`, `light`, `normal`, `medium`, `bold`, `black`
+
+---
+
+## The Vault (Backend Security)
+
+Code in the `server` block runs **exclusively on the server**. The compiler strips it completely from the client bundle.
+
+```yaml
+server
+    import db from "luxaura/db"
+
+    def getUser(id):
+        # This code NEVER reaches the browser
+        return db.query("SELECT * FROM users WHERE id = ?", [id])
+```
+
+Frontend calls it naturally:
+
+```yaml
+view
+    Action "Load User"
+        on click:
+            result = await server.getUser(userId)
+```
+
+Features:
+- **Auto-CSRF**: Every RPC request is signed with a rotating token
+- **Auto-Sanitization**: String inputs are sanitized before processing
+- **Code Stripping**: Build verifiably excludes server code from `dist/client`
+
+---
+
+## The Physics Engine (Auto-Responsiveness)
+
+Layouts adapt automatically without media queries:
+
+- `Row` → stacks to `Column` on mobile
+- Buttons/inputs auto-enlarge to 44px touch targets on mobile
+- `Image` with `responsive: true` never overflows its container
+- `Nav` auto-collapses on small screens
+
+---
+
+## Utility Classes
+
+```html
+<!-- In your .lux view or class: attributes -->
+class: "lux-flex lux-center lux-gap-4"
+class: "lux-text-xl lux-font-bold lux-text-primary"
+class: "lux-card lux-shadow-lg lux-rounded-lg"
+```
+
+Full class list available in `luxaura.min.css`.
+
+---
+
+## Modules (Built-in API)
+
+```yaml
+server
+    import db      from "luxaura/db"      # Database queries
+    import router  from "luxaura/router"  # Navigation
+    import http    from "luxaura/http"    # External API calls
+    import auth    from "luxaura/auth"    # Authentication
+    import storage from "luxaura/storage" # localStorage wrapper
+```
+
+---
+
+## Headless Mode
+
+Use Luxaura as a frontend-only framework, proxying to any backend:
+
+```
+# luxaura.config
+mode: headless
+proxy: http://localhost:8080
+```
+
+API requests are automatically forwarded to your existing backend.
+
+---
+
+## Plugin System
+
+```bash
+luxaura install tailwindcss
+luxaura install bootstrap
+```
+
+Then use classes directly in your `.lux` views:
+
+```yaml
+view
+    Box
+        Action "Submit"
+            class: "bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
+```
+
+---
+
+## Project Structure
+
+```
+my-app/
+├── luxaura.config        # Global config (theme, db, mode)
+├── assets/               # Images, fonts (auto-optimized)
+├── pages/                # Route entry points (index.lux, about.lux)
+├── modules/              # Reusable components (Navbar.lux, Card.lux)
+├── server/               # Shared server utilities
+└── dist/
+    ├── client/           # Public assets (HTML, JS, CSS)
+    └── server/           # Secure server modules (Vault)
+```
+
+---
+
+## Programmatic API
+
+```javascript
+const luxaura = require('luxaura');
+
+// Parse a .lux file
+const ast = luxaura.parse(source, 'MyComponent.lux');
+
+// Compile AST to JS/CSS/HTML
+const output = luxaura.compile(ast, { componentName: 'MyComponent' });
+
+console.log(output.clientJS);  // Client bundle
+console.log(output.serverJS);  // Server vault module
+console.log(output.css);       // Component styles
+console.log(output.html);      // HTML shell
+
+// One-shot transform
+const output2 = luxaura.transform(source, 'MyComponent.lux');
+```
+
+---
+
+## Runtime JavaScript API
+
+```javascript
+// Mount a component
+const ctx = window.__Lux__.mount('MyApp', '#root', { title: 'Hello' });
+
+// Toast notifications
+__Lux__.toast.success('Saved!');
+__Lux__.toast.error('Something went wrong');
+__Lux__.toast.info('Loading...');
+
+// Theme switching
+__Lux__.setTheme('dark');
+__Lux__.setTheme('light');
+
+// Navigation
+__Lux__.router.navigate('/about');
+
+// HTTP requests
+const data = await __Lux__.http.get('https://api.example.com/data');
+
+// Storage
+__Lux__.storage.local.set('key', 'value');
+__Lux__.storage.local.get('key');
+```
+
+---
+
+## Security
+
+Run the built-in security scanner before deploying:
+
+```bash
+luxaura secure
+```
+
+Detects:
+- XSS risks (`innerHTML`, `eval`, `document.write`)
+- SQL injection patterns (string concatenation in queries)
+- Accidental server code outside `server` blocks
+- Sensitive environment variable exposure
+
+---
+
+## License
+
+MIT © Luxaura Contributors