npm package: @imedrebhi/luxaura
Description: Intent-Based Full-Stack Web Framework — build apps with .lux files
Author: Imed Rebhi
Latest version: 1.0.0

# 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