inertia-angular 3.7.1

package/readme.md

@@ -0,0 +1,173 @@
+# Inertia.js Angular Adapter
+
+An Angular 22 adapter for [Inertia.js](https://inertiajs.com/). It uses standalone components, signals, dependency injection, zoneless change detection, AOT, and Angular's native SSR and hydration APIs.
+
+This is a community package. It is not maintained by the Inertia.js team and Angular is not an officially supported Inertia adapter.
+
+## Installation
+
+```sh
+pnpm add inertia-angular @angular/common @angular/core @angular/platform-browser
+```
+
+`@inertiajs/core` is installed automatically. Angular `>=22.1 <23` is supported by this release.
+
+The version number tracks Inertia itself, so `inertia-angular@3.7.1` targets `@inertiajs/core@3.7.x`. A patch release of this package can run ahead of Inertia's own when it only fixes the Angular side.
+
+Do not install Angular Router: Inertia owns navigation, URL history, scroll restoration, cached pages, and visits.
+
+## Server side
+
+Any Inertia server adapter works, because this package only replaces the client. There is no Vite plugin involved: the Angular CLI is the bundler, so build your entry point with `ng build` and point the server's root template at the output.
+
+With Laravel, install `inertiajs/inertia-laravel` and build into `public/build/angular` with a matching `baseHref`:
+
+```html
+<link rel="stylesheet" href="/build/angular/styles.css" />
+<script type="module" src="/build/angular/main.js"></script>
+@inertiaHead
+```
+
+With AdonisJS, install `@adonisjs/inertia` and reference the built files from the Edge root template by hand, instead of through `@adonisjs/vite`.
+
+A complete Laravel setup, including the SSR build, lives in [playgrounds/angular](https://github.com/gerardp/inertia-angular/tree/main/playgrounds/angular).
+
+## Bootstrap
+
+Add a stable host and the serialized initial page to the document generated by your server adapter:
+
+```html
+<script data-page="app" type="application/json">…</script>
+<div id="app"></div>
+```
+
+Then bootstrap the adapter:
+
+```ts
+import { createInertiaApp } from 'inertia-angular'
+import { pages } from './pages'
+
+void createInertiaApp({
+  resolve: (name) => pages[name],
+  progress: { color: '#dd0031' },
+})
+```
+
+The resolver may return a component, a promise, or a module with a default component. It receives both the component name and the current Inertia page. `setup` can take over application creation when a custom host bootstrap is required. `withApp` returns providers scoped to the browser application or an individual SSR render.
+
+## Pages and props
+
+Pages are standalone Angular components. Props used as direct bindings must be declared as inputs because Angular cannot spread arbitrary object keys onto a component:
+
+```ts
+import { Component, input } from '@angular/core'
+import { usePage } from 'inertia-angular'
+
+@Component({
+  selector: 'users-show',
+  template: '<h1>{{ user().name }}</h1><small>{{ page().url }}</small>',
+})
+export default class ShowUser {
+  readonly user = input.required<{ name: string }>()
+  readonly page = usePage()
+}
+```
+
+`usePage()` returns the same read-only `Signal<Page>` throughout the current injector. The complete props object always remains available there, including props that are not declared as component inputs.
+
+On a preserved component, an input that was previously present and is removed by a later response is written as `undefined` so stale values cannot survive. An input transform used for removable props must therefore accept `undefined`. An input that has never been supplied keeps its Angular initializer.
+
+## Layouts
+
+Layouts render an explicit `<inertia-layout-outlet />`. This keeps dynamically nested views inside Angular's view tree and makes them compatible with SSR hydration; dynamically passing DOM nodes through `projectableNodes` is not hydratable in Angular.
+
+```ts
+import { Component } from '@angular/core'
+import { LayoutOutlet, type ResolvedComponent } from 'inertia-angular'
+
+@Component({
+  selector: 'site-layout',
+  imports: [LayoutOutlet],
+  template: '<nav>…</nav><main><inertia-layout-outlet /></main>',
+})
+export class SiteLayout {}
+
+@Component({ selector: 'dashboard-page', template: '<h1>Dashboard</h1>' })
+export default class Dashboard {
+  static layout = SiteLayout
+}
+```
+
+Single and nested layouts, tuple props, `{ component, props }`, named layouts, callbacks based on page props, a default layout, and render functions using `h()` are supported. Compatible layout instances remain mounted across Inertia visits. `useLayoutProps()` updates shared or named layout inputs from descendants.
+
+## Navigation and data loading
+
+`Link` is a directive for semantic native elements:
+
+```html
+<a inertiaLink href="/users" prefetch="hover">Users</a>
+<button inertiaLink href="/users" method="post">Create user</button>
+```
+
+The package also exports signal-based `usePoll`, `usePrefetch`, `useRemember`, `Deferred`, `WhenVisible`, and `InfiniteScroll`. Their listeners, observers, and polling timers are tied to the current Angular lifecycle. `usePoll()` returns `start()`, `stop()`, and a read-only `polling()` signal.
+
+### Visit callbacks and Angular outputs
+
+`Link` and `Form` expose Inertia visit callbacks as function-valued signal inputs. Use these inputs when the callback controls the visit: `onBefore` may synchronously return `false` to cancel it, and a promise returned by `onSuccess` delays completion.
+
+```html
+<button inertiaLink href="/users" [onBefore]="confirmVisit" [onSuccess]="afterSuccess">Users</button>
+```
+
+The corresponding Angular outputs use event binding syntax, such as `(before)` and `(success)`, and are notification-only. Values returned by an output listener are ignored, so outputs cannot cancel a visit or delay its lifecycle. Use the `[on…]` callback inputs whenever return values or sequencing matter.
+
+## Forms
+
+`useForm()` and `useHttp()` expose data and status as signals and include nested paths, defaults, reset/error helpers, remembered state, optimistic updates, cancellation, file uploads, and Precognition validation. They delegate transport to `@inertiajs/core`; Angular `HttpClient` is not involved.
+
+For native forms, apply `inertiaForm` and use `exportAs` for state and methods:
+
+```html
+<form inertiaForm method="post" action="/users" #form="inertiaForm">
+  <input name="name" />
+  @if (form.errors().name) { <p>{{ form.errors().name }}</p> }
+  <button type="submit" [disabled]="form.processing()">Save</button>
+</form>
+```
+
+`useFormContext()` reads the closest form directive from a descendant. `createForm<T>()` is a compile-time marker for strict-template form field types; it does not create state.
+
+Call `form.cancel()` to cancel a submission. Set `[cancelOnUnmount]="true"` to cancel a pending submission when the form is destroyed; the default is `false`. The `(cancel)` output remains available for notifications. `useForm()` submissions also continue after destruction unless explicitly cancelled.
+
+## Head
+
+`Head` is a directive on an Angular template. It supports a title input and arbitrary keyed tags:
+
+```html
+<ng-template inertiaHead title="Dashboard">
+  <meta head-key="description" name="description" content="Dashboard" />
+</ng-template>
+```
+
+## SSR and hydration
+
+Install `@angular/platform-server` and use the secondary entry point:
+
+```ts
+import { createServer, renderAngularApp } from 'inertia-angular/server'
+
+const render = (page) => renderAngularApp(page, { resolve: (name) => pages[name] })
+createServer(render)
+```
+
+Each render creates a new Angular application, injector, runtime, page signal, head manager, and layout store. The framework-agnostic `router`, `config`, `http`, `progress`, and interceptor registry in `@inertiajs/core` remain module singletons. Keep their defaults and HTTP client stable within one SSR process; request-specific configuration of those singletons is not isolated.
+
+The browser entry automatically enables Angular hydration when the server-rendered host has `data-server-rendered`. The serialized host, hydration annotations, whitespace, comments, and transfer-state scripts are preserved.
+
+## Deliberate Angular differences
+
+- Inertia replaces Angular Router for Inertia page navigation.
+- Layouts use `LayoutOutlet` instead of `<ng-content>` so dynamic layout trees hydrate correctly.
+- Direct page/layout props require declared Angular inputs; the whole page is available from `usePage()`.
+- `Link`, `Form`, and `InfiniteScroll` are directives on native elements instead of components that select an element by string.
+- The package is standalone, zoneless, and does not require `NgModule` or `zone.js`.

package/resources/boost/guidelines/core.blade.php

@@ -0,0 +1,9 @@
+# Inertia + Angular
+
+Inertia owns navigation, history, scroll restoration, caching, and visits. Do not add Angular Router to an Inertia application.
+
+Page and layout props used as direct bindings must be declared as Angular inputs. The complete page object is always available through `usePage()`.
+
+Use standalone, zoneless Angular components. A persistent layout imports `LayoutOutlet` and renders `<inertia-layout-outlet />` where its child layout or page belongs.
+
+Use `Link`, `Form`, and `InfiniteScroll` on semantic native elements. Use `useForm()` or `useHttp()` for signal-based form state; do not introduce Angular `HttpClient` as a second Inertia transport.

package/types/inertia-angular-server.d.ts

@@ -0,0 +1,18 @@
+export { default as createServer } from '@inertiajs/core/server';
+import { PageProps, Page, InertiaAppSSRResponse } from '@inertiajs/core';
+export { InertiaAppSSRResponse } from '@inertiajs/core';
+import { ComponentResolver, AngularWithApp } from 'inertia-angular';
+
+interface RenderAngularAppOptions<SharedProps extends PageProps = PageProps> {
+    id?: string;
+    resolve: ComponentResolver;
+    title?: (title: string, page: Page) => string;
+    layout?: (name: string, page: Page) => unknown;
+    serverHead?: boolean | string | ((page: Page) => string[] | null | undefined);
+    withApp?: AngularWithApp<SharedProps>;
+    document?: string;
+}
+declare function renderAngularApp<SharedProps extends PageProps = PageProps>(page: Page<SharedProps>, options: RenderAngularAppOptions<SharedProps>): Promise<InertiaAppSSRResponse>;
+
+export { renderAngularApp };
+export type { RenderAngularAppOptions };