@orieljs/framework 0.1.0-alpha.1 → 0.1.0-alpha.11

package/docs/inertia.md

@@ -0,0 +1,485 @@
+# Inertia
+
+Inertia lets you write your pages as React, Vue, Svelte, Solid or Angular components, while your routes and controllers
+stay on the server, with no API to build in between.
+
+## Introduction
+
+An Inertia page is a component in `resources/js/pages`. Your controller returns the page's name and its props; Inertia
+renders the component with them, in the browser on later visits and, with server-side rendering, on the server for the
+first one. Links and forms make requests as a single-page app does, and the server answers with the next page's props as
+JSON.
+
+Oriel follows `inertia-laravel` on the server and speaks the protocol of the official Inertia clients. Its adapters,
+one per framework, add typed pages and Oriel's `route()`:
+
+| Framework | Package | Starter kit |
+| --- | --- | --- |
+| React | `@orieljs/inertia-react` | `--inertia=react` |
+| Vue | `@orieljs/inertia-vue` | `--inertia=vue` |
+| Svelte | `@orieljs/inertia-svelte` | `--inertia=svelte` |
+| Solid | `@orieljs/inertia-solid` | `--inertia=solid` |
+| Angular | `@orieljs/inertia-angular` | `--inertia=angular` |
+
+The React, Vue and Svelte adapters are the official Inertia adapters, re-exported with Oriel's additions. The Solid
+and Angular adapters are Oriel's own, with the same API in each framework's idiom. A new app from an Inertia
+[starter kit](starter-kits.md) has everything below set up.
+
+## Server-side setup
+
+### Creating responses
+
+An action returns a page with `inertia()`, its component's name and its props:
+
+```ts title="app/Http/Controllers/PostController.ts"
+import { inertia } from '@orieljs/framework'
+import { Post } from '../../Models/Post'
+import { Controller } from './Controller'
+
+export class PostController extends Controller {
+  /** Show the blog's posts. */
+  async index() {
+    return inertia('Posts/Index', {
+      posts: await Post.latest().get(),
+    })
+  }
+}
+```
+
+The component's name is its path under `resources/js/pages`, without the extension: `Posts/Index` is
+`resources/js/pages/Posts/Index.tsx` (or `.vue`, `.svelte`, `.component.ts`). Models in the props reach the page as
+their JSON, so their `hidden` attributes stay on the server.
+
+A page with no data of its own needs no controller: `Route.inertia()` routes a URI to it.
+
+```ts title="routes/web.ts"
+import { Route } from '@orieljs/framework'
+
+Route.inertia('/about', 'About').name('about')
+```
+
+### The root view
+
+The first visit loads the root view, `resources/views/app.tsx`, which writes the HTML document around the page. It
+places the page's data with `inertiaBody(page)`, the server-rendered head with `inertiaHead(page)`, and your scripts and
+styles with [`vite()`](vite.md). A React app adds `viteReactRefresh()` before `vite()`:
+
+```tsx title="resources/views/app.tsx"
+import { inertiaBody, inertiaHead, vite, viteReactRefresh } from '@orieljs/framework'
+import type { InertiaPage } from '@orieljs/framework/contracts'
+
+export default function App({ page }: { page: InertiaPage }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        {inertiaHead(page)}
+        {viteReactRefresh()}
+        {vite(['resources/css/app.css', 'resources/js/app.tsx'])}
+      </head>
+      <body>{inertiaBody(page)}</body>
+    </html>
+  )
+}
+```
+
+### The middleware
+
+`HandleInertiaRequests`, in `app/Http/Middleware`, extends `InertiaMiddleware`, and `bootstrap/app.ts` appends it to the
+`web` group. It answers in the Inertia protocol: a JSON page on Inertia requests, a 409 when your assets changed since
+the page was loaded, and a 303 after a `PUT`, `PATCH` or `DELETE` that redirects. `node oriel inertia:middleware` writes
+one for an app that hasn't.
+
+Its `share()` gives every page some props, merged with the validation errors it shares itself:
+
+```ts title="app/Http/Middleware/HandleInertiaRequests.ts"
+import { Auth, config, InertiaMiddleware } from '@orieljs/framework'
+import type { HttpRequest } from '@orieljs/framework/contracts'
+import type { User } from '../../Models/User'
+
+export class HandleInertiaRequests extends InertiaMiddleware {
+  /** The root view loaded on the first page visit: resources/views/app.tsx. */
+  protected override rootViewName = 'app'
+
+  /** Props shared with every page. */
+  override async share(request: HttpRequest) {
+    const user = await Auth.user<User>()
+
+    return {
+      ...(await super.share(request)),
+      name: String(config('app.name')),
+      auth: { user: user === undefined ? null : { id: user.id, name: user.name, email: user.email } },
+    }
+  }
+}
+```
+
+`version()` returns your assets' version: a hash of `app.asset_url` when you set one, else of
+`public/build/manifest.json`. A page loaded with an older version is reloaded in full on its next visit.
+
+### Shared data
+
+Besides the middleware's `share()`, `Inertia.share()` shares props from anywhere in a request, such as a controller:
+
+```ts
+Inertia.share('appName', 'Blog')
+```
+
+`Inertia.flash()` stores data for the next page only, which reads it as `page.flash`, as session flash data works.
+
+### Redirects
+
+Redirect as anywhere else in your app: `redirect().route('posts.index')`, or `back()`. Inertia follows the redirect
+and shows the next page. To leave the app, to an external site or a page that isn't Inertia's, `Inertia.location()`
+makes the browser load the URL in full:
+
+```ts
+Route.get('/billing', () => Inertia.location('https://example.com/billing'))
+```
+
+### Props: deferred, optional and merged
+
+A prop can be a function, which runs only when the prop is sent. These helpers choose when that is:
+
+| Helper | The prop is sent |
+| --- | --- |
+| `Inertia.defer(fn, group?)` | In a request the page makes right after it renders, so the page shows sooner; props of one group come together |
+| `Inertia.optional(fn)` | Only in a partial reload that asks for it |
+| `Inertia.always(value)` | In every response, even a partial reload that didn't ask for it |
+| `Inertia.merge(value)`, `Inertia.deepMerge(value)` | And merged into the page's current value on a reload, such as the next page of a list |
+| `Inertia.once(fn)` | Once: the client keeps it for the next pages |
+| `Inertia.scroll(paginator)` | As a page of an infinite scroll, with its page numbers |
+
+```ts title="app/Http/Controllers/DashboardController.ts"
+import { Inertia, inertia } from '@orieljs/framework'
+import { Post } from '../../Models/Post'
+import { Controller } from './Controller'
+
+export class DashboardController extends Controller {
+  async index() {
+    return inertia('Dashboard', {
+      latest: await Post.latest().limit(5).get(),
+      drafts: Inertia.defer(() => Post.whereNull('published_at').get()),
+      stats: Inertia.optional(() => Post.count()),
+    })
+  }
+}
+```
+
+A partial reload asks the server for some props only, such as `router.reload({ only: ['stats'] })` in the page.
+
+## Client-side setup
+
+The browser entry, `resources/js/app.tsx` (`app.ts` in the Vue, Svelte and Angular kits), starts Inertia with your
+pages' folder:
+
+```tsx title="resources/js/app.tsx"
+import { createInertiaApp } from '@orieljs/inertia-react'
+
+const appName = import.meta.env.VITE_APP_NAME || 'Oriel'
+
+createInertiaApp({
+  pages: './pages',
+  title: (title) => (title ? `${title} – ${appName}` : appName),
+})
+```
+
+`title` formats every page's title. The `oriel()` [Vite](vite.md) plugin sets up each framework's own Vite plugin.
+
+## Pages
+
+A page component receives its props. They are typed: `node oriel inertia:types` reads the `inertia()` calls of your
+controllers and routes and writes `resources/js/oriel/pages.d.ts`, so each page knows its props, and the props your
+middleware shares. The kits' Vite plugin runs it when Vite starts, and again when your server code changes.
+
+```tsx tab="React" title="resources/js/pages/Posts/Index.tsx"
+import { Head, Link, route, type PageProps } from '@orieljs/inertia-react'
+
+export default function Index({ posts }: PageProps<'Posts/Index'>) {
+  return (
+    <>
+      <Head title="Posts" />
+      <ul>
+        {posts.map((post) => (
+          <li key={post.id}>
+            <Link href={route('posts.show', post.slug)}>{post.title}</Link>
+          </li>
+        ))}
+      </ul>
+    </>
+  )
+}
+```
+```vue tab="Vue" title="resources/js/pages/Posts/Index.vue"
+<script setup lang="ts">
+import { Head, Link, route, usePage } from '@orieljs/inertia-vue'
+
+const page = usePage<'Posts/Index'>()
+</script>
+
+<template>
+  <Head title="Posts" />
+  <ul>
+    <li v-for="post in page.props.posts" :key="post.id">
+      <Link :href="route('posts.show', post.slug)">{{ post.title }}</Link>
+    </li>
+  </ul>
+</template>
+```
+```svelte tab="Svelte" title="resources/js/pages/Posts/Index.svelte"
+<script lang="ts">
+  import { Link, route, type PageProps } from '@orieljs/inertia-svelte'
+
+  let { posts }: PageProps<'Posts/Index'> = $props()
+</script>
+
+<svelte:head>
+  <title>Posts</title>
+</svelte:head>
+
+<ul>
+  {#each posts as post (post.id)}
+    <li><Link href={route('posts.show', post.slug)}>{post.title}</Link></li>
+  {/each}
+</ul>
+```
+```tsx tab="Solid" title="resources/js/pages/Posts/Index.tsx"
+import { Head, Link, route, type PageProps } from '@orieljs/inertia-solid'
+import { For } from 'solid-js'
+
+export default function Index(props: PageProps<'Posts/Index'>) {
+  return (
+    <>
+      <Head title="Posts" />
+      <ul>
+        <For each={props.posts}>
+          {(post) => (
+            <li>
+              <Link href={route('posts.show', post.slug)}>{post.title}</Link>
+            </li>
+          )}
+        </For>
+      </ul>
+    </>
+  )
+}
+```
+```ts tab="Angular" title="resources/js/pages/Posts/Index.component.ts"
+import { Component, input } from '@angular/core'
+import { Head, Link, route } from '@orieljs/inertia-angular'
+
+@Component({
+  selector: 'posts-index',
+  imports: [Head, Link],
+  template: `
+    <o-head title="Posts" />
+    <ul>
+      @for (post of posts(); track post.id) {
+        <li><a oLink [href]="route('posts.show', post.slug)">{{ post.title }}</a></li>
+      }
+    </ul>
+  `,
+})
+export default class Index {
+  readonly posts = input.required<{ id: number; title: string; slug: string }[]>()
+
+  protected readonly route = route
+}
+```
+
+> [!NOTE]
+> A Vue page reads its props with `usePage<'Posts/Index'>()`, typed by the page's name, where Inertia's own Vue docs
+> declare them with `defineProps`: Vue's compiler can't resolve the generated page types in
+> `defineProps<PageProps<'Posts/Index'>>()`. An Angular page receives each prop as a signal input. Svelte has no
+> Inertia `Head` component: the kits use `<svelte:head>`.
+
+### Links and the route helper
+
+`Link` (in Angular, the `oLink` directive on an `<a>`) visits a page without reloading the document. `route()` gives a
+named route's URL, typed: once `node oriel route:types` has run, a wrong name or a missing parameter is a type error.
+`isCurrentRoute('posts.*')` tells you whether the current page's route matches, for an active link. Both work during
+server-side rendering, from the URL being rendered.
+
+`router` makes visits from code: `router.visit(url)`, `router.post(url, data)`, `router.reload({ only: ['stats'] })`.
+
+## Forms
+
+`useForm()` holds a form's data, sends it, and gives back the validation errors, one per field, and whether the
+request is in flight:
+
+```tsx tab="React" title="resources/js/pages/Posts/Create.tsx"
+import { route, useForm } from '@orieljs/inertia-react'
+import type { FormEvent } from 'react'
+
+export default function Create() {
+  const { data, setData, post, processing, errors } = useForm<{ title: string }>({ title: '' })
+
+  const submit = (event: FormEvent) => {
+    event.preventDefault()
+    post(route('posts.store'))
+  }
+
+  return (
+    <form onSubmit={submit}>
+      <input value={data.title} onChange={(event) => setData('title', event.target.value)} />
+      {errors.title && <p className="error">{errors.title}</p>}
+
+      <button type="submit" disabled={processing}>
+        Publish
+      </button>
+    </form>
+  )
+}
+```
+```vue tab="Vue" title="resources/js/pages/Posts/Create.vue"
+<script setup lang="ts">
+import { route, useForm } from '@orieljs/inertia-vue'
+
+const form = useForm({
+  title: '',
+})
+
+const submit = () => {
+  form.post(route('posts.store'))
+}
+</script>
+
+<template>
+  <form @submit.prevent="submit">
+    <input v-model="form.title" />
+    <p v-if="form.errors.title" class="error">{{ form.errors.title }}</p>
+
+    <button type="submit" :disabled="form.processing">Publish</button>
+  </form>
+</template>
+```
+```svelte tab="Svelte" title="resources/js/pages/Posts/Create.svelte"
+<script lang="ts">
+  import { route, useForm } from '@orieljs/inertia-svelte'
+
+  const form = useForm({
+    title: '',
+  })
+
+  function submit(event: SubmitEvent) {
+    event.preventDefault()
+    form.post(route('posts.store'))
+  }
+</script>
+
+<form onsubmit={submit}>
+  <input bind:value={form.title} />
+  {#if form.errors.title}
+    <p class="error">{form.errors.title}</p>
+  {/if}
+
+  <button type="submit" disabled={form.processing}>Publish</button>
+</form>
+```
+```tsx tab="Solid" title="resources/js/pages/Posts/Create.tsx"
+import { route, useForm } from '@orieljs/inertia-solid'
+import { Show } from 'solid-js'
+
+export default function Create() {
+  const form = useForm<{ title: string }>({ title: '' })
+
+  const submit = (event: SubmitEvent) => {
+    event.preventDefault()
+    form.post(route('posts.store'))
+  }
+
+  return (
+    <form onSubmit={submit}>
+      <input value={form.data.title} onInput={(event) => form.setData('title', event.currentTarget.value)} />
+      <Show when={form.errors.title}>
+        <p class="error">{form.errors.title}</p>
+      </Show>
+
+      <button type="submit" disabled={form.processing}>
+        Publish
+      </button>
+    </form>
+  )
+}
+```
+```ts tab="Angular" title="resources/js/pages/Posts/Create.component.ts"
+import { Component } from '@angular/core'
+import { route, useForm } from '@orieljs/inertia-angular'
+
+@Component({
+  selector: 'posts-create',
+  template: `
+    <form (submit)="submit($event)">
+      <input #title [value]="form.data.title" (input)="form.setData('title', title.value)" />
+      @if (form.errors.title) {
+        <p class="error">{{ form.errors.title }}</p>
+      }
+
+      <button type="submit" [disabled]="form.processing">Publish</button>
+    </form>
+  `,
+})
+export default class Create {
+  protected readonly form = useForm<{ title: string }>({ title: '' })
+
+  protected submit(event: SubmitEvent): void {
+    event.preventDefault()
+    this.form.post(route('posts.store'))
+  }
+}
+```
+
+A failed validation sends the user back to the page, with the errors (see
+[Displaying errors in Inertia pages](validation.md#displaying-errors-in-inertia-pages)). Each adapter also has a `Form`
+component (Angular's `form[oForm]`), which sends a plain HTML form's fields without `useForm()`.
+
+### Precognition
+
+On a route with the `precognitive` middleware, the React, Vue and Svelte forms can validate a field while the user fills
+it in: give `useForm()` the method and the URL first, `useForm('post', route('posts.store'), { title: '' })`, then call
+`form.validate('title')`; `Form` has a `validate()` too. The Solid and Angular forms don't offer Precognition yet.
+[Precognition](validation.md#precognition) describes the server side, and why the action validates first.
+
+## More Inertia features
+
+Each adapter has Inertia's components and hooks for the props above, under Inertia's names (Angular's are directives):
+
+| Feature | React, Vue, Svelte, Solid | Angular |
+| --- | --- | --- |
+| Deferred props, with a fallback while they load | `Deferred` | `oDeferred` directive |
+| Loading props when an element scrolls into view | `WhenVisible` | `oWhenVisible` directive |
+| Infinite scrolling of an `Inertia.scroll()` prop | `InfiniteScroll` | `<o-infinite-scroll>` |
+| Reloading props on an interval | `usePoll()` | `usePoll()` |
+| Prefetching pages before a click | `usePrefetch()`, `prefetch` on `Link` | `usePrefetch()`, `prefetch` on `oLink` |
+| Keeping local state in the browser's history | `useRemember()` | `useRemember()` |
+| The page's title and meta tags | `Head` (Svelte: `<svelte:head>`) | `<o-head>` |
+
+They work as Inertia's documentation describes, at [inertiajs.com](https://inertiajs.com).
+
+## Server-side rendering
+
+The React, Vue, Svelte and Solid kits render the first visit on the server, so it arrives as HTML. `npm run build`
+builds the server bundle from `resources/js/ssr.*` into `bootstrap/ssr`, and `node oriel inertia:start-ssr` runs it;
+when no SSR server answers, the pages are rendered in the browser. [Inertia SSR](starter-kits.md#inertia-ssr) and
+[The SSR server](deployment.md#the-ssr-server) cover running it. `inertia.ssr.enabled`, from `INERTIA_SSR_ENABLED`,
+turns it off.
+
+## History encryption
+
+Inertia keeps each page's props in the browser's history, so the back button can show them again. To keep a signed-in
+user's data out of it after they sign out, encrypt it: `INERTIA_ENCRYPT_HISTORY=true` encrypts every page's state, and
+the `inertia.encrypt` middleware does it for some routes. `Inertia.clearHistory()` clears the encrypted history, such
+as when a user signs out.
+
+## Adapter differences
+
+| | React, Vue, Svelte | Solid | Angular |
+| --- | --- | --- | --- |
+| Server-side rendering | Yes | Yes | No |
+| Precognition | Yes | No | No |
+| `useHttp()` | Yes | No | No |
+
+The Angular adapter's other limits are in its package's README: track a form's array rows by `$index` or a stable id,
+not by the item, since `useForm` copies the objects along a dotted path on each write; and once a page uses `<o-head>`,
+a later `Title.setTitle()` is overwritten.