payload-live-preview 2.0.0-beta.0 → 2.0.0

package/dist/adapters/nextjs/index.d.ts

@@ -1,9 +1,11 @@
-import { b as PreviewAdapterOptions } from '../../options-CEzzfHJu.js';
+import { P as PreviewAdapterOptions } from '../../options-BW1eqXvc.js';
+import { F as FragmentEndpointOptions$1, a as FragmentRegistry$1, b as FragmentRegistryEntry$1, c as FragmentRenderer$1, d as FragmentRenderInput } from '../../fragment-endpoint-3Mlz7GDz.js';
 
 /**
- * Next.js adapter. `renderLivePreviewScript()` in the root layout is the
- * primary wiring: `NextResponse.next()` carries no body, so the middleware
- * only injects into responses that actually carry HTML.
+ * Next.js adapter. The script goes into the root layout, because
+ * `NextResponse.next()` carries no body for the middleware to inject into:
+ * `livePreviewScriptProps()` for the App Router's JSX, `renderLivePreviewScript()`
+ * for HTML a server assembles as a string.
  */
 
 type LivePreviewNextOptions = PreviewAdapterOptions;
@@ -14,9 +16,248 @@ type LivePreviewNextOptions = PreviewAdapterOptions;
  * `authorizePreviewRequest()` in the route when a page needs it.
  */
 declare function createLivePreviewMiddleware(options?: LivePreviewNextOptions): (request: Request, response: Response) => Promise<Response>;
-/** The `<script>` tag for `app/layout.tsx`; pass the nonce your CSP uses. */
+/** What a `<script>` element needs to carry the runtime; see `livePreviewScriptProps`. */
+interface LivePreviewScriptProps {
+    readonly dangerouslySetInnerHTML: {
+        readonly __html: string;
+    };
+    /** Present only when a nonce was passed, so React omits the attribute otherwise. */
+    readonly nonce?: string;
+}
+/**
+ * Props for the `<script>` in `app/layout.tsx`:
+ *
+ * ```tsx
+ * <script {...livePreviewScriptProps({ allowedOrigins: [ADMIN], serverURL: ADMIN, mergeDepth: 1 })} />
+ * ```
+ *
+ * The nonce stays a prop rather than going into the body, because that is where
+ * the framework — and any CSP handling built on it — expects the attribute.
+ */
+declare function livePreviewScriptProps(options?: LivePreviewNextOptions & {
+    readonly nonce?: string;
+}): LivePreviewScriptProps;
+/**
+ * The complete `<script>` tag, for HTML a server builds as a string. A JSX
+ * framework cannot render it — use `livePreviewScriptProps()` there.
+ */
 declare function renderLivePreviewScript(options?: LivePreviewNextOptions & {
     readonly nonce?: string;
 }): string;
 
-export { type LivePreviewNextOptions, PreviewAdapterOptions, createLivePreviewMiddleware, renderLivePreviewScript };
+/**
+ * A React function component.
+ *
+ * The parameter is `never` rather than the props object it will receive:
+ * parameters are checked contravariantly, so this accepts a component with any
+ * props while a `Record<string, unknown>` would accept almost none. What the
+ * component and its props have to agree on is checked by `defineFragment()`,
+ * which is why that helper exists.
+ */
+type ReactComponentLike = (props: never) => unknown;
+type FragmentRegistryEntry<Props extends object = object> = FragmentRegistryEntry$1<ReactComponentLike, Props>;
+/** @internal */
+type FragmentRegistry = FragmentRegistry$1<ReactComponentLike>;
+/** @internal */
+type FragmentRenderer = FragmentRenderer$1<ReactComponentLike>;
+type FragmentEndpointOptions = FragmentEndpointOptions$1<ReactComponentLike>;
+/**
+ * Pairs a component with the props it takes, so the two cannot drift apart.
+ * Without it a registry entry types its props as any record and a renamed prop
+ * is found by the editor, in the preview, at the worst moment.
+ *
+ * ```ts
+ * const registry = { hero: defineFragment(Hero, ({ fields }) => ({ title: String(fields.title ?? '') })) };
+ * ```
+ */
+declare function defineFragment<Props extends object>(component: (props: Props) => unknown, props: (input: FragmentRenderInput) => Props | Promise<Props>): FragmentRegistryEntry<Props>;
+/** Build the endpoint; export it as the `POST` of an App Router route handler. */
+declare function createFragmentEndpoint(options: FragmentEndpointOptions): (request: Request) => Promise<Response>;
+
+/**
+ * `withLivePreview(nextConfig)` — the parts of a Next.js setup that belong in
+ * `next.config.ts` rather than in a layout: the admin's host in
+ * `allowedDevOrigins`, so Next's dev server does not refuse the admin's own
+ * server actions behind a proxy, and `private, no-store` on a request that
+ * carries preview intent.
+ *
+ * What it cannot do is inject the script: no config hook renders HTML. That
+ * stays one import and one spread in `app/layout.tsx` (docs/nextjs.md), so this
+ * is a two-line setup, not a one-line one — said plainly rather than implied
+ * away.
+ *
+ * **And it writes no CSP.** A config rule cannot run `authorizePreview`, so it
+ * can never be the place a privileged response change is decided (ADR 0006 §5).
+ * It could not even widen `frame-ancestors` safely: Next collects every
+ * matching rule into one object keyed by header name and applies it with
+ * `setHeader`, and these rules are appended after the consumer's, so a policy
+ * written here replaces the one the site already sends instead of adding to
+ * it. Measured on Next.js 16.3.4 (`next build` + `next start`): a site sending
+ * `frame-ancestors 'none'` answered a bare `/?preview=true` with
+ * `frame-ancestors 'self' <admin>` and nothing else — its `script-src` gone,
+ * for anyone who appends the query parameter. `frame-ancestors` for the admin
+ * origin is `createLivePreviewMiddleware`'s, which merges into an existing
+ * policy and only once the engine has authorized the request.
+ */
+/** The slice of `next.config` this touches; everything else is passed through. */
+interface NextConfigLike {
+    readonly allowedDevOrigins?: readonly string[];
+    readonly headers?: () => Promise<readonly NextHeaderRule[]> | readonly NextHeaderRule[];
+    readonly [option: string]: unknown;
+}
+interface NextHeaderRule {
+    readonly source: string;
+    readonly headers: readonly {
+        readonly key: string;
+        readonly value: string;
+    }[];
+    readonly has?: readonly {
+        readonly type: string;
+        readonly key: string;
+        readonly value?: string;
+    }[];
+    readonly [option: string]: unknown;
+}
+interface WithLivePreviewOptions {
+    /** Payload admin origins. Required; their hosts are what `allowedDevOrigins` needs. */
+    readonly allowedOrigins: readonly string[];
+    /**
+     * Query parameters that mark preview intent, matching the runtime's own
+     * defaults. The cache header is set only for requests carrying one of them.
+     */
+    readonly previewQueryParams?: readonly string[];
+    /** Add the admin origins to `allowedDevOrigins`. Default `true`. */
+    readonly allowDevOrigins?: boolean;
+}
+/** One rule per intent parameter: Next matches `has` entries as a conjunction. @internal */
+declare function previewHeaderRules(options: WithLivePreviewOptions): readonly NextHeaderRule[];
+/**
+ * ```ts
+ * // next.config.ts
+ * export default withLivePreview(nextConfig, {
+ *   allowedOrigins: [process.env.NEXT_PUBLIC_PAYLOAD_URL!],
+ * });
+ * ```
+ */
+declare function withLivePreview(nextConfig: NextConfigLike, options: WithLivePreviewOptions): NextConfigLike;
+
+/**
+ * The route half of `delivery: 'asset'` for Next.js.
+ *
+ * ```ts
+ * // app/payload-live-preview/[file]/route.ts
+ * import { createRuntimeAssetRoute } from 'payload-live-preview/nextjs';
+ *
+ * export const { GET } = createRuntimeAssetRoute();
+ * ```
+ *
+ * The dynamic segment is what carries the content hash. The handler answers
+ * only the file name this package build produces and 404s everything else, so a
+ * client holding a year-old `immutable` copy of some other build gets an
+ * honest miss rather than different bytes under the same name.
+ *
+ * No route segment config is exported with it. `dynamic: 'force-static'` would
+ * be tempting — the bytes are the same for every request — but on a dynamic
+ * segment it asks Next to prerender one arbitrary param at build time. The
+ * caching that matters is the response's own `immutable`, which browsers and
+ * CDNs honour without Next's help.
+ */
+
+/** What a route file re-exports. */
+interface RuntimeAssetRoute {
+    readonly GET: (request: Request) => Response;
+}
+/**
+ * Takes the adapter's own options so the one object can be passed to both
+ * halves: only `assetPath` and `runtime` are read, but those two are exactly
+ * what the page and the route have to agree on, and `runtime: LEAN_RUNTIME`
+ * means the page asks for that artifact's hash.
+ */
+declare function createRuntimeAssetRoute(options?: LivePreviewNextOptions): RuntimeAssetRoute;
+
+/**
+ * `<LivePreviewScript />` — the delivery that charges an anonymous visitor
+ * nothing.
+ *
+ * A root layout renders for every request, and the two helpers that served it
+ * until now build the script whoever is asking: `livePreviewScriptProps()` and
+ * `renderLivePreviewScript()` are synchronous, so they cannot wait for a
+ * verdict and do not try. That is why the demo answered a `curl` without a
+ * cookie with 195 342 of 254 707 bytes of preview runtime — once in the
+ * document, once more escaped into the RSC flight payload underneath it.
+ *
+ * An async server component can wait. This one runs the same policy every
+ * adapter runs — intent, then `authorizePreview` — and returns `null` unless
+ * the answer is yes. Not a few hundred bytes of bootstrap for the public:
+ * nothing, the same as the Astro middleware, the SvelteKit handle and the Nuxt
+ * Nitro plugin already deliver.
+ *
+ * **`next` is not imported here and must not become a dependency.** The
+ * component takes the request as a prop, the way `<LivePreviewRouteRefresh />`
+ * takes the router's refresh, and the caller builds it from what the framework
+ * hands a server component:
+ *
+ * ```tsx
+ * // app/layout.tsx — the App Router
+ * import { headers } from 'next/headers';
+ * import { LivePreviewScript } from 'payload-live-preview/nextjs';
+ *
+ * export default async function RootLayout({ children }: { children: ReactNode }) {
+ *   return (
+ *     <html lang="en">
+ *       <head>
+ *         <LivePreviewScript
+ *           request={new Request(SITE_URL, { headers: await headers() })}
+ *           inject="always"
+ *           allowedOrigins={[ADMIN_URL]}
+ *           authorizePreview={authorize}
+ *         />
+ *       </head>
+ *       <body>{children}</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ *
+ * A `Request` rather than a shape of our own: it is what `authorizePreview`
+ * and `shouldInject` already receive from the middleware, so one options object
+ * serves both entry points and neither hook has to be written twice.
+ *
+ * The URL is the caller's to supply, and the recipe above says why `headers()`
+ * alone is not enough: Next gives a server component the request headers and
+ * cookies but not its URL, so a layout cannot see `?preview=true` and the
+ * `query` signal — the 2.0 default — cannot fire there. `inject: 'always'`
+ * then makes `authorizePreview` the single gate, which is the stricter reading
+ * anyway and exactly what LP-8 needs. A page, which does get `searchParams`,
+ * can pass the real URL and keep intent as the cheap pre-filter it is.
+ * docs/nextjs.md carries both recipes.
+ */
+
+/** What the component takes: every adapter option, plus the request it decides for. */
+interface LivePreviewScriptComponentProps extends LivePreviewNextOptions {
+    /**
+     * The request this render answers: in the App Router, a `Request` built from
+     * the URL and `await headers()`. A promise is accepted so the caller need not
+     * resolve `headers()` first.
+     */
+    readonly request: Request | Promise<Request>;
+    /** CSP nonce for the element, when the application manages one. */
+    readonly nonce?: string;
+}
+/**
+ * The `<script>` this resolves to, described structurally rather than as
+ * `ReactElement`: the entry must not carry React's types any more than its
+ * code, and a JSX consumer accepts this shape as a node all the same.
+ */
+interface LivePreviewScriptElement {
+    readonly type: 'script';
+    readonly props: LivePreviewScriptProps;
+    readonly key: null;
+}
+/**
+ * Renders the runtime for an authorized preview and nothing at all for
+ * everyone else. Mount it in the layout or page that owns `<head>`.
+ */
+declare function LivePreviewScript(props: LivePreviewScriptComponentProps): Promise<LivePreviewScriptElement | null>;
+
+export { type FragmentEndpointOptions, type FragmentRegistry, type FragmentRegistryEntry, FragmentRenderInput, type FragmentRenderer, type LivePreviewNextOptions, LivePreviewScript, type LivePreviewScriptComponentProps, type LivePreviewScriptElement, type LivePreviewScriptProps, type NextConfigLike, type NextHeaderRule, PreviewAdapterOptions, type ReactComponentLike, type RuntimeAssetRoute, type WithLivePreviewOptions, createFragmentEndpoint, createLivePreviewMiddleware, createRuntimeAssetRoute, defineFragment, livePreviewScriptProps, previewHeaderRules, renderLivePreviewScript, withLivePreview };