payload-live-preview 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,472 @@
+import { l as LivePreviewPlugin, e as FieldRenderer } from './bind-BSgxoQhN.cjs';
+export { B as BindOptions, C as CachedElement, a as CspDirectiveMerge, E as EventEmitter, b as EventHandler, F as FieldBindingAttributes, c as FieldName, d as FieldPath, f as FieldTransform, g as FieldType, h as FrameAncestorsOptions, L as LIBRARY_PROTOCOL_VERSION, i as LivePreviewClient, j as LivePreviewClientConfig, k as LivePreviewEventMap, O as OriginDetector, P as PayloadFieldSchema, m as PayloadFieldType, n as PayloadLivePreviewData, o as PayloadLivePreviewMessage, p as PluginContext, q as ProtocolCapability, r as ProtocolNegotiation, R as RenderContext, S as SanitizerDocument, U as Unsubscribe, V as VERSION, s as ValueAt, t as bind, u as bindByPath, v as buildFrameAncestors, w as buildScriptSrcWithNonce, x as detectInitialLocale, y as escapeHtml, z as escapeHtmlAttribute, A as generateCspNonce, D as hasCapability, G as initLivePreview, H as isDevMode, I as isExternalHttpUrl, J as isInIframe, K as isInPopup, M as isInPreviewContext, N as isSafeUrl, Q as mergeCspHeader, T as negotiateProtocol, W as sanitizeHtml, X as setCspCrypto, Y as setSanitizerDocument } from './bind-BSgxoQhN.cjs';
+export { P as PreviewRequestLike, a as PreviewRequestOptions, i as isPreviewRequest } from './preview-request-DAvxm18T.cjs';
+
+interface RuntimeBuildInfo {
+    readonly generatedAt: string;
+    readonly size: number;
+}
+
+/**
+ * Inline script generator.
+ *
+ * Wraps the build-time-generated runtime IIFE with consumer-provided
+ * configuration. Returns a JavaScript string suitable for embedding
+ * via `<script>` in any framework.
+ *
+ * The runtime body is identical to the one used by the high-level
+ * client because both originate from `src/core/runtime.ts`. There is
+ * no parallel implementation to drift out of sync.
+ *
+ * @module @inline/generator
+ */
+
+interface InlineScriptConfig {
+    /** Additional trusted origins to merge with auto-detected ones. */
+    readonly allowedOrigins?: readonly string[];
+    /**
+     * Payload server origin, e.g. `https://cms.example.com`. When set,
+     * every incoming update is re-fetched through the Payload REST API
+     * (`X-Payload-HTTP-Method-Override: GET`, same strategy as the
+     * official client) so relationship and upload fields render
+     * populated instead of as bare IDs. Strongly recommended for
+     * Payload 3.x. Requires the preview page to be able to reach the
+     * API with credentials (same-site cookies or CORS `credentials`).
+     */
+    readonly serverURL?: string;
+    /** REST API route prefix used with `serverURL`. Defaults to `/api`. */
+    readonly apiRoute?: string;
+    /** Population depth used with `serverURL`. Defaults to `1`. */
+    readonly mergeDepth?: number;
+    /** Enable verbose console logging. Defaults to `false`. */
+    readonly debug?: boolean;
+    /** Debounce window for incoming updates in ms. Defaults to `50`. */
+    readonly debounceMs?: number;
+    /** Enable screen-reader live region. Defaults to `true`. */
+    readonly enableA11y?: boolean;
+    /**
+     * Heartbeat timeout in ms. Defaults to `0` (disabled). The Payload
+     * admin only posts messages on form edits — there is no protocol
+     * keepalive — so an idle-based timeout would fire spurious
+     * disconnects while the editor pauses. Enable only if your admin
+     * setup sends periodic messages.
+     */
+    readonly heartbeatMs?: number;
+    /**
+     * Bypass the visibility-gate optimisation and apply every update
+     * regardless of viewport position. Default `false` — the gate kicks
+     * in when the cache exceeds `visibilityGateThreshold` entries.
+     */
+    readonly disableVisibilityGate?: boolean;
+    /**
+     * Cache-size threshold above which the visibility gate activates.
+     * Default `50`. Off-screen elements above this threshold are queued
+     * for replay on intersection instead of being updated immediately.
+     */
+    readonly visibilityGateThreshold?: number;
+    /**
+     * `rootMargin` passed to the `IntersectionObserver` watching the
+     * cached elements. Default `'200px'`. Increase to pre-render
+     * further off-screen content; decrease for tighter visibility.
+     */
+    readonly intersectionRootMargin?: string;
+    /**
+     * Opt out of `document.referrer`-based origin auto-detection.
+     * Useful when the page is loaded under `Referrer-Policy: no-referrer`
+     * and you want predictable behaviour. Default `false`.
+     */
+    readonly disableReferrerDetection?: boolean;
+    /**
+     * Opt out of the dev-mode localhost-pattern matcher (any port on
+     * `localhost` / `127.0.0.1`). Useful when running locally against
+     * a production-like origin list. Default `false`.
+     */
+    readonly disableLocalhostMatching?: boolean;
+    /**
+     * Optional CSP nonce for the generated `<script>` tag. When provided
+     * via `wrapWithScriptTag()` the nonce is set on the tag. Useful for
+     * strict CSP policies that disallow `unsafe-inline`.
+     */
+    readonly nonce?: string;
+}
+/**
+ * Build an inline script body. The result is a self-contained IIFE
+ * with the build-time runtime, prefixed by a configuration block.
+ *
+ * The string does NOT include the `<script>` tags — use
+ * `wrapWithScriptTag()` when you need them.
+ */
+declare function generateInlineScript(config?: InlineScriptConfig): string;
+/**
+ * Wrap an inline script body in a `<script>` tag. When a nonce is
+ * provided it is added as the `nonce` attribute so CSP policies that
+ * require `'nonce-...'` accept the script.
+ */
+declare function wrapWithScriptTag(body: string, options?: {
+    nonce?: string;
+}): string;
+/**
+ * Snapshot of the build-time information for diagnostics.
+ */
+declare function runtimeBuildInfo(): RuntimeBuildInfo;
+
+/**
+ * Draft-aware document fetching for the initial preview render.
+ *
+ * The live-preview runtime patches the DOM *after* the page loads —
+ * the initial server render is the consumer's job. With Payload
+ * drafts enabled, a preview must render the **draft** version on
+ * first load, otherwise editors see stale published content until
+ * their first keystroke.
+ *
+ * These helpers wrap the two REST queries every preview loader needs,
+ * with the right flags (`draft=true`, `depth`) and an explicit nudge
+ * to keep `depth` in sync with the runtime's `mergeDepth` — a
+ * mismatch makes populated relationships degrade to IDs after the
+ * first edit.
+ *
+ * Isomorphic and dependency-free: works in Astro frontmatter,
+ * SvelteKit `load`, Next.js server components, or any Node/edge
+ * runtime with `fetch`.
+ *
+ * ```ts
+ * // Astro frontmatter
+ * const page = await fetchPreviewDocument<Page>({
+ *   serverURL: import.meta.env.PAYLOAD_URL,
+ *   collection: 'pages',
+ *   where: { slug: { equals: Astro.params.slug } },
+ *   draft: isPreviewRequest(Astro.request),
+ *   headers: { Authorization: `users API-Key ${import.meta.env.PAYLOAD_PREVIEW_KEY}` },
+ * });
+ * ```
+ *
+ * @module @preview-fetch
+ */
+interface PreviewFetchBaseOptions {
+    /** Payload server origin, e.g. `https://cms.example.com`. */
+    readonly serverURL: string;
+    /** REST API route prefix. Defaults to `/api`. */
+    readonly apiRoute?: string;
+    /**
+     * Population depth. Defaults to `1`. ⚠️ Keep this equal to the
+     * runtime's `mergeDepth` — the live-merge re-fetches with that
+     * depth, and a mismatch makes nested relationships flip between
+     * objects and IDs mid-session.
+     */
+    readonly depth?: number;
+    /**
+     * Fetch the draft version. Defaults to `true` (this is a *preview*
+     * fetch). Pass the result of `isPreviewRequest(request)` to make
+     * the same loader serve published content to normal traffic.
+     */
+    readonly draft?: boolean;
+    /** Locale to fetch. */
+    readonly locale?: string;
+    /**
+     * Extra request headers — typically auth, since draft reads require
+     * an authenticated user (e.g. `Authorization: users API-Key …`).
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Injectable fetch implementation (tests, custom agents). */
+    readonly fetchFn?: typeof fetch;
+}
+/** Payload `where` clause — kept loose on purpose (server validates). */
+type PreviewWhere = Readonly<Record<string, unknown>>;
+interface FetchPreviewDocumentOptions extends PreviewFetchBaseOptions {
+    /** Collection slug. */
+    readonly collection: string;
+    /** Fetch a single document by id. Mutually exclusive with `where`. */
+    readonly id?: string | number;
+    /**
+     * Fetch the first document matching this Payload `where` clause,
+     * e.g. `{ slug: { equals: 'about' } }`.
+     */
+    readonly where?: PreviewWhere;
+}
+interface FetchPreviewGlobalOptions extends PreviewFetchBaseOptions {
+    /** Global slug. */
+    readonly global: string;
+}
+/**
+ * Fetch a single collection document (draft-first by default).
+ * Returns `null` when nothing matches or the request fails —
+ * loaders should fall back to their regular data path or a 404.
+ */
+declare function fetchPreviewDocument<T = Record<string, unknown>>(options: FetchPreviewDocumentOptions): Promise<T | null>;
+/**
+ * Fetch a global (draft-first by default). Returns `null` on failure.
+ */
+declare function fetchPreviewGlobal<T = Record<string, unknown>>(options: FetchPreviewGlobalOptions): Promise<T | null>;
+
+/**
+ * Generic Lexical node. Concrete renderers consume specific subtypes
+ * through narrow type guards in their own modules.
+ */
+interface LexicalNode {
+    readonly type: string;
+    readonly version?: number;
+    readonly format?: number | string;
+    readonly indent?: number;
+    readonly direction?: 'ltr' | 'rtl' | null;
+    readonly children?: readonly LexicalNode[];
+    readonly text?: string;
+    readonly [extra: string]: unknown;
+}
+/**
+ * Root of a Lexical document.
+ */
+interface LexicalRoot {
+    readonly root: {
+        readonly type?: string;
+        readonly children: readonly LexicalNode[];
+        readonly direction?: 'ltr' | 'rtl' | null;
+        readonly format?: number | string;
+        readonly indent?: number;
+        readonly [extra: string]: unknown;
+    };
+}
+
+/**
+ * Top-level Lexical → HTML renderer.
+ *
+ * Walks the document tree, dispatching each node to the renderer
+ * registered for its `type`. Unknown nodes are handled gracefully:
+ * children are rendered (so the user sees content), the wrapper is
+ * skipped.
+ *
+ * @module @lexical/render
+ */
+
+interface LexicalRenderOptions {
+    /**
+     * When `true` (default), the resulting HTML is passed through the
+     * isomorphic `sanitizeHtml()` for defence-in-depth.
+     */
+    readonly sanitize?: boolean;
+}
+/**
+ * Identify whether a value looks like a Lexical root payload.
+ */
+declare function isLexicalContent(value: unknown): value is LexicalRoot;
+/**
+ * Convert a Lexical root payload to an HTML string. By default the
+ * result is sanitised through `sanitizeHtml`. The renderer is
+ * security-first; per-node renderers already escape text and validate
+ * URLs, but the final sanitiser closes any gap.
+ */
+declare function lexicalToHtml(content: LexicalRoot, options?: LexicalRenderOptions): string;
+/**
+ * Extract the plain text content of a Lexical document.
+ *
+ * Paragraphs are separated by `\n`. Used by the text/textarea renderer
+ * when a rich-text value is bound to a non-rich-text element.
+ */
+declare function lexicalToPlainText(content: LexicalRoot): string;
+
+/**
+ * Block-renderer sub-registry.
+ *
+ * Payload's BlocksFeature emits Lexical `block` nodes with a
+ * `blockType` slug. The default `block`-node renderer (in
+ * `../nodes/block.ts`) only emits a generic
+ * `<div data-block-type="…">` — useful as a hook, but unhelpful when
+ * the consumer wants out-of-the-box rendering for common block types.
+ *
+ * This registry maps `blockType` → renderer. Default renderers ship
+ * for the most common Payload block patterns (callout, image,
+ * video, code, cta). Custom slugs override defaults via
+ * `registerBlockRenderer(slug, renderer)`.
+ *
+ * @module @lexical/blocks/registry
+ */
+
+/**
+ * Context passed to a block renderer. Includes the recursive
+ * `renderChildren` function so blocks that house nested Lexical
+ * content can delegate back to the main renderer.
+ */
+interface BlockRenderContext {
+    /** Renders a list of Lexical children to HTML. */
+    readonly renderChildren: (children: readonly LexicalNode[]) => string;
+}
+/**
+ * Renderer signature. Receives the block node *and* its already-read
+ * `fields` payload (the parser pulls these out so individual block
+ * renderers don't have to reach into `node['fields']` themselves).
+ */
+type BlockRenderer = (fields: Record<string, unknown>, context: BlockRenderContext) => string;
+/** Register or replace the renderer for `blockType`. */
+declare function registerBlockRenderer(blockType: string, renderer: BlockRenderer): void;
+
+/**
+ * `highlight` plugin — flashes an outline on updated elements so the
+ * editor can see what changed.
+ *
+ * Respects `prefers-reduced-motion`. Adds at most one style tag per
+ * document.
+ *
+ * @module @plugins/built-in/highlight
+ */
+
+declare const highlightPlugin: LivePreviewPlugin;
+
+/**
+ * `debug` plugin — logs every lifecycle event via the plugin context.
+ *
+ * @module @plugins/built-in/debug
+ */
+
+declare const debugPlugin: LivePreviewPlugin;
+
+/**
+ * `analytics` plugin — accumulates summary statistics about the
+ * update stream. Useful for performance dashboards.
+ *
+ * The plugin owns its own state (no module singleton) and exposes it
+ * via the `getStats` factory passed through the plugin's `init` hook
+ * by closing over a local object.
+ *
+ * @module @plugins/built-in/analytics
+ */
+
+interface AnalyticsSnapshot {
+    readonly updateCount: number;
+    readonly totalElements: number;
+    readonly totalDurationMs: number;
+    readonly averageDurationMs: number;
+}
+declare function createAnalyticsPlugin(): LivePreviewPlugin & {
+    readonly getStats: () => AnalyticsSnapshot;
+};
+
+/**
+ * `documentSave` plugin — react to Payload document-save events with
+ * out-of-the-box strategies. Most consumers just want one of these:
+ *
+ *   - `'silent'` (default) → only emit the event, do nothing else.
+ *   - `'reload'`           → reload the page, **preserving the scroll
+ *                            position** across the reload (the
+ *                            framework-agnostic analog of Payload's
+ *                            `RefreshRouteOnSave`).
+ *   - `'revalidate'`       → POST to a revalidation endpoint (Astro,
+ *                            Next.js convention) so SSR caches refresh
+ *                            without losing client state.
+ *   - `'fetch'`            → custom async handler supplied by the user.
+ *
+ * Each strategy is intentionally narrow so consumers can compose them
+ * — e.g. revalidate, then if revalidation fails, fall back to reload.
+ *
+ * @module @plugins/built-in/document-save
+ */
+
+type DocumentSaveStrategy = 'silent' | 'reload' | 'revalidate' | 'fetch';
+interface DocumentSavePluginOptions {
+    /** Strategy to invoke on each `documentSave` event. Default `'silent'`. */
+    readonly strategy?: DocumentSaveStrategy;
+    /**
+     * For `'revalidate'`: endpoint to POST to. Defaults to `/api/revalidate`.
+     * The request body is `{ source: 'payload-live-preview' }` JSON.
+     */
+    readonly revalidateUrl?: string;
+    /**
+     * For `'revalidate'`: extra headers (e.g., `Authorization: Bearer …`).
+     * The `Content-Type: application/json` header is set automatically.
+     */
+    readonly revalidateHeaders?: Readonly<Record<string, string>>;
+    /**
+     * For `'fetch'`: async handler called on each event. The plugin
+     * awaits it; rejections are logged but don't crash the runtime.
+     */
+    readonly handler?: () => void | Promise<void>;
+    /**
+     * Optional fallback strategy when `'revalidate'` POST fails (network
+     * error or non-2xx). Set to `'reload'` to hard-refresh the page when
+     * SSR-cache invalidation can't be confirmed.
+     */
+    readonly onRevalidateFailure?: 'silent' | 'reload';
+}
+/**
+ * Build the plugin. Pass it to `client.use(documentSavePlugin({ … }))`.
+ */
+declare function documentSavePlugin(options?: DocumentSavePluginOptions): LivePreviewPlugin;
+
+/**
+ * Field-renderer registry.
+ *
+ * Maps a `FieldType` to the function that mutates a DOM element with
+ * the new value. The registry pattern decouples the lifecycle from the
+ * concrete renderers, so:
+ *
+ *   - Tests can substitute mock renderers.
+ *   - Plugins can register custom renderers via the high-level client.
+ *   - New field types ship without touching `lifecycle.ts`.
+ *
+ * The built-in renderers are collected through `registerBuiltinRenderer`
+ * from each renderer module. To avoid tree-shaking, the explicit
+ * aggregator `buildBuiltinRenderers` accepts an *additional* renderer
+ * array — `@field-types/index` invokes it with every concrete renderer
+ * so the references stay reachable.
+ *
+ * @module @field-types/registry
+ */
+
+/**
+ * Register a built-in renderer. Called from each individual renderer
+ * module's side-effecting registration.
+ */
+declare function registerBuiltinRenderer(renderer: FieldRenderer): void;
+
+/**
+ * Shared shapes for the field-type renderers.
+ *
+ * @module @field-types/types
+ */
+interface PayloadMedia {
+    readonly id?: string | number;
+    readonly url?: string;
+    readonly alt?: string;
+    readonly filename?: string;
+    readonly mimeType?: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly sizes?: Readonly<Record<string, {
+        readonly url?: string;
+        readonly width?: number;
+        readonly height?: number;
+    }>>;
+}
+/**
+ * Generic relationship payload. The optional `TSlug` parameter is a
+ * phantom marker that codegen uses to record the target collection(s)
+ * without changing the runtime shape — `PayloadRelationship<'users'>`
+ * and `PayloadRelationship<'users' | 'authors'>` behave identically at
+ * runtime but carry different types at compile time.
+ */
+interface PayloadRelationship<TSlug extends string = string> {
+    readonly id?: string | number;
+    readonly title?: string;
+    readonly name?: string;
+    readonly slug?: string;
+    readonly url?: string;
+    readonly relationTo?: TSlug;
+    readonly [extra: string]: unknown;
+}
+
+/**
+ * Public barrel for built-in field renderers.
+ *
+ * Each renderer is imported as a named binding (not a side-effect)
+ * and assembled into the registry through `buildBuiltinRenderers`.
+ * The bundler keeps every reference reachable, so the registry is
+ * fully populated at runtime even under `sideEffects: false`.
+ *
+ * @module @field-types
+ */
+
+/**
+ * Built-in renderer map. Calling this from the runtime adds every
+ * concrete renderer to the registry and snapshots the result.
+ */
+declare function buildBuiltinRenderers(): Readonly<Record<string, FieldRenderer>>;
+
+export { type AnalyticsSnapshot, type BlockRenderContext, type BlockRenderer, type DocumentSavePluginOptions, type DocumentSaveStrategy, type FetchPreviewDocumentOptions, type FetchPreviewGlobalOptions, FieldRenderer, type InlineScriptConfig, type LexicalNode, type LexicalRoot, LivePreviewPlugin, type PayloadMedia, type PayloadRelationship, type PreviewFetchBaseOptions, type PreviewWhere, buildBuiltinRenderers, createAnalyticsPlugin, debugPlugin, documentSavePlugin, fetchPreviewDocument, fetchPreviewGlobal, generateInlineScript, highlightPlugin, isLexicalContent, lexicalToHtml, lexicalToPlainText, registerBlockRenderer, registerBuiltinRenderer, runtimeBuildInfo, wrapWithScriptTag };