# Leaf 5: Views & Frontend Reference

## Overview

| Engine | Speed | Features | Use Case |
|---|---|---|---|
| **BareUI** | ⚡️ Fast | Basic (pure PHP) | Simple/performance-critical views |
| **Blade** | Moderate | Rich (`@` directives) | Full-featured templating |
| **Inertia** | N/A | React/Vue/Svelte | SPA-style frontend frameworks |

---

## BareUI

Lightweight, pure PHP templating. No compilation, no caching, just speed.

```bash
leaf install bareui
```

### Setup (Basic app only: MVC pre-configured)

```php
app()->template()->config('path', './views');
```

### Template Files

Extension: `.view.php`

```php
<!-- welcome.view.php -->
<h1>Hello <?php echo $name; ?></h1>

<?php if (count($items) > 0) : ?>
    <ul>
        <?php foreach ($items as $item) : ?>
            <li><?php echo $item['name']; ?></li>
        <?php endforeach; ?>
    </ul>
<?php else : ?>
    <p>No items</p>
<?php endif; ?>
```

### Render

```php
response()->render('welcome');
response()->render('welcome', ['name' => 'Michael', 'items' => $items]);
```

### Sub-templates / Partials

All BareUI templates have access to `$template`:

```php
<?php echo $template::render('partials/header'); ?>
<?php echo $template::render('partials/footer', ['year' => date('Y')]); ?>
```

> XSS protection is handled automatically by Leaf Anchor when using Leaf's request functions.

---

## Blade

Laravel's templating engine. Pre-installed in MVC.

```bash
leaf install blade@v4   # Basic app
```

### Render

```php
response()->render('hello', ['name' => 'Michael']);    // hello.blade.php
```

### Core Directives

```blade
{{-- Output (auto-escaped) --}}
{{ $name }}

{{-- Unescaped output --}}
{!! $html !!}

{{-- PHP blocks --}}
@php $x = 1; @endphp

{{-- Conditionals --}}
@if ($condition) ... @elseif ($other) ... @else ... @endif

{{-- Loops --}}
@foreach ($items as $item) ... @endforeach
@for ($i = 0; $i < 10; $i++) ... @endfor
@while ($condition) ... @endwhile
```

### Leaf-specific Directives

```blade
{{-- CSRF token: renders the hidden token field ONLY when the leafs/csrf
     module is installed; without it, @csrf renders nothing (by design, so
     scaffolds can carry it). Do not debug missing token fields in templates:
     run `leaf install csrf` instead. --}}
<form method="POST">
    @csrf
    ...
</form>

{{-- Auth state --}}
@auth  // user is logged in  @endauth
@guest // user is not logged in  @endguest

{{-- Roles & permissions --}}
@is('admin') ... @endis
@can('edit articles') ... @endcan

{{-- Environment --}}
@env('production') ... @else ... @endenv

{{-- Null check --}}
@isNull($variable) ... @else ... @endisNull

{{-- Session --}}
@session('status')
    <div>{{ $value }}</div>
@endsession

{{-- Flash messages --}}
@flash('status')
    <div>{{ $message }}</div>
@endflash

{{-- JSON --}}
<script>var app = @json($array);</script>

{{-- Vite assets --}}
@vite('app.js')
@vite(['app.js', 'app.css'])

{{-- Alpine.js --}}
<head>
    @alpine
</head>

{{-- Toast notifications --}}
<body>
    ...
    @toastContainer
</body>

{{-- i18n --}}
<h1>@lingo('hero.title')</h1>
```

### Conditional HTML Attributes

```blade
@class(['p-4', 'font-bold' => $isActive, 'bg-red' => $hasError])
@style(['background-color: red', 'font-weight: bold' => $isActive])
@checked($isActive)
@selected($shouldBeSelected)
@disabled($shouldBeDisabled)
@readonly($shouldBeReadonly)
@required($shouldBeRequired)
```

### Custom Directives

```php
app()->blade()->directive('datetime', function ($expression) {
    return "<?php echo tick({$expression})->format('DD MM YYYY'); ?>";
});
```

Usage: `@datetime($date)`

---

## Inertia (React / Vue / Svelte)

Connects Leaf backend to a JS frontend framework without building a full API.

### Setup (MVC)

```bash
leaf view:install --vue
leaf view:install --react
leaf view:install --svelte
```

When you run `view:install`, Leaf automatically generates `app/views/_inertia.blade.php`, the root HTML shell for all Inertia pages. **Do not create this file manually.**

```blade
{{-- app/views/_inertia.blade.php (auto-generated) --}}
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title inertia>{{ _env('APP_NAME', 'Leaf MVC') }}</title>
    @viteReactRefresh
    @vite(['/js/app.jsx', "/js/pages/{$page['component']}.jsx"])
    @inertiaHead
</head>
<body>
    @inertia
</body>
</html>
```

**This is the right place for global head content**, fonts, analytics (GTM, Tawk.to, OneSignal), favicon, CDN scripts, etc. Edit it when you need those things; otherwise leave it alone.

```blade
{{-- _inertia.blade.php with global assets --}}
<head>
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link href="https://fonts.googleapis.com/css2?family=Inter&display=swap" rel="stylesheet">
    @viteReactRefresh
    @vite(['/js/app.jsx', "/js/pages/{$page['component']}.jsx"])
    @inertiaHead
    {{-- GTM, analytics, chat widgets go here --}}
</head>
<body>
    @inertia
</body>
```

Key directives:
- `@viteReactRefresh`, React HMR in dev (must come before `@vite`)
- `@vite([...])`, loads compiled assets
- `@inertiaHead`, renders `<Head>` tags from React components
- `@inertia`, mounts the React/Vue/Svelte app

### Returning Inertia Views

```php
// From controller
response()->inertia('home', ['user' => auth()->user()]);

// Direct route
app()->inertia('/home', 'home');
```

Naming: page files are kebab-case in lowercase folders (`pages/order-history.jsx`), and the string you pass to `response()->inertia()` matches the file name exactly. The component *inside* the file keeps React's PascalCase convention. Prefer `response()->inertia()` over the bare `inertia()` helper, it returns a response like every other handler.

### Generating View Files

```bash
leaf g:template home              # auto-detects framework
leaf g:template home --type=jsx   # React
leaf g:template home --type=vue
leaf g:template home --type=svelte
```

### Shared Data (across all views)

```php
// app/routes/index.php
use Leaf\Inertia;

Inertia::share('appName', 'My App');
Inertia::share('flash', function () {
    return flash()->display('flash') ?? null;
});
```

Leaf automatically shares an `auth` prop with every Inertia page: `{id, user, roles, permissions, errors}`. Do not share your own `auth` key, the framework's value takes precedence and yours never renders. `auth.user` contains every column not listed in auth's `hidden` config.

### React Component Example

```jsx
export default function Home({ user, appName }) {
    return <h1>Welcome to {appName}, {user.name}</h1>;
}
```

### Form Validation with Inertia

Controller:
```php
$data = request()->validate(['email' => 'email']);

if (!$data) {
    return response()
        ->withFlash('errors', request()->errors())
        ->withFlash('old', request()->body())   // optional: what was typed, so the form is not empty after the redirect
        ->redirect('/form', 303);  // 303 is important for Inertia
}
```

Every Inertia page automatically carries an `errors` prop read from the `errors` flash bag (leafs/inertia 5.1+), shaped `{field: "message"}` the way Inertia clients expect, and cleared on the next visit. The view does not pass it by hand:

```php
response()->inertia('form', ['old' => flash()->display('old') ?? []]);
```

Frontend (React):
```jsx
export default function Form({ old }) {
    const { data, setData, post, errors } = useForm({ email: old.email ?? '' });
    // errors.email is populated from the shared errors prop; usePage().props.errors has the same object
}
```

Leaf's validator can hold several messages per field; the prop keeps the first. To build the bag yourself (a service rejecting a save, not the validator), flash `['field' => 'message']`. A page that passes its own `errors` prop, or `Inertia::share('errors', ...)`, overrides the shared one.

### Not-found pages with a real 404

Inertia clients accept any status on a response that carries the `X-Inertia` header, so a missing record renders the not-found page and still answers 404 to crawlers, `curl` and monitoring:

```php
// app/routes/index.php
app()->set404(fn () => response()->inertia('not-found', [], 404));

// a controller
if (!$post) {
    return response()->inertia('not-found', [], 404);
}
```

`response()->inertia($page, $props, $status)`, `inertia()` and `Inertia::render()` all take the status as the third argument (leafs/inertia 5.1+). Without it the shell is served with 200 whatever the route decided.

### shadcn/ui (React)

```bash
leaf scaffold:shadcn
pnpm dlx shadcn@latest add button
```

---

## Lite Apps

Everything above works in lite apps too, with a few differences in layout:

- `leaf view:install --react` (or `--vue` / `--svelte`) works in lite apps and writes frontend files to `views/js/` in the project root, not `app/views/`, that path belongs to the MVC layout.
- Lite apps must configure the view paths before rendering. Newly scaffolded apps have this wired automatically as of CLI v5.0.6; older apps need it set by hand:

```php
app()->config('views.path', 'views');
app()->config('views.cache', __DIR__ . '/storage/cache');
```

- Vite serves from the project root in lite apps: the `hot` file and the `build/` directory live at the root, which matches leafs/vite's defaults (5.x latest). MVC apps use `public/` instead, wired automatically.
- `g:template` and `scaffold:*` commands are MVC-only. They don't exist in a lite app's console, so create page files by hand.

---

## Vite (Asset Bundling)

Pre-installed in MVC. For Basic apps:

```bash
leaf view:install --vite
```

### Loading Assets

```blade
@vite('css/app.css')
@vite(['app.css', 'app.js'])
```

PHP (non-Blade):
```php
<?php vite('css/app.css'); ?>
```

### `vite.config.js`

```js
import { defineConfig } from 'vite';
import leaf from '@leafphp/vite-plugin';

export default defineConfig({
    plugins: [
        leaf({
            input: ['path/to/app.css', 'path/to/app.js'],
            refresh: true,
        }),
    ],
    resolve: {
        alias: { '@': '/path/to/folder' },
    },
});
```

### PHP Config (optional, non-MVC)

```php
\Leaf\Vite::config([
    'assets' => 'app/views',
    'build'  => 'public/build',
]);
```

Vite dev server starts automatically with `leaf serve`.

---

## Tailwind CSS

```bash
leaf view:install --tailwind
```

Installs Tailwind v4, updates `vite.config.js`, and sets up `css/app.css`.

Include in Blade layout:
```blade
@vite('css/app.css')
```

### Theming (Tailwind v4)

```css
@theme {
  --color-primary: #ff0000;
  --color-secondary: #00ff00;
}
```

```html
<div class="bg-primary text-secondary">Hello</div>
```

---

## Custom / Third-Party Template Engines

### Basic App

```php
app()->attachView(Smarty::class);
app()->smarty()->setTemplateDir('/views');
app()->smarty()->assign('name', 'Michael');
app()->smarty()->display('index.tpl');
```

### MVC: `config/view.php`

```bash
leaf config:publish view   # → config/view.php
```

```php
return [
    'viewEngine' => \Smarty::class,

    'config' => function (\Smarty $engine, array $config) {
        $engine->setTemplateDir($config['views']);
        $engine->setCacheDir($config['cache']);
    },

    'render' => function (\Smarty $engine, $view, $data) {
        foreach ($data as $key => $value) {
            $engine->assign($key, $value);
        }
        $engine->display($view);
    },

    'extend' => null,
];
```
