payload-live-preview 1.0.5 → 1.2.0

package/dist/index.d.cts

@@ -379,6 +379,15 @@ interface CachedElement {
     readonly arraySeparator?: string;
     /** Optional locale code locked onto this element (overrides the global locale). */
     readonly locale?: string;
+    /**
+     * Optional document this binding belongs to, resolved from the nearest
+     * `data-payload-owner` ancestor (the element itself included).
+     *
+     * Only consulted while owner scoping is enabled. Without it a field name is
+     * the sole identity, so every document rendered on the page competes for the
+     * same name.
+     */
+    readonly owner?: string;
 }
 /**
  * Context passed to every field renderer. Provides access to the
@@ -550,6 +559,20 @@ interface LivePreviewClientConfig {
     readonly heartbeatMs?: number;
     /** IntersectionObserver rootMargin. Defaults to `200px`. */
     readonly intersectionRootMargin?: string;
+    /**
+     * Restrict each update to the bindings owned by the document it describes.
+     *
+     * Ownership is declared in markup with `data-payload-owner`, resolved from
+     * the nearest ancestor: `global:<slug>`, `collection:<slug>`, or
+     * `collection:<slug>:<id>`. Payload already sends the edited document's
+     * identity, so nothing else needs configuring.
+     *
+     * Defaults to `false`, which keeps the 1.x behaviour of matching on the
+     * field name alone. Enable it when one page previews more than one document
+     * and a field name is therefore no longer a unique identity. While enabled,
+     * a binding without an owner is never updated.
+     */
+    readonly scopeBindingsByOwner?: boolean;
     /** Bypass the visibility gate (apply every update). Defaults to `false`. */
     readonly disableVisibilityGate?: boolean;
     /** Cache-size threshold above which off-screen updates are queued for replay. Defaults to 50. */
@@ -721,6 +744,15 @@ interface InlineScriptConfig {
      * a production-like origin list. Default `false`.
      */
     readonly disableLocalhostMatching?: boolean;
+    /**
+     * Restrict each update to the bindings owned by the document it describes,
+     * declared in markup with `data-payload-owner` and resolved from the nearest
+     * ancestor. Default `false`, which keeps matching on the field name alone.
+     *
+     * Enable it when one page previews more than one document. While enabled a
+     * binding without an owner is never updated.
+     */
+    readonly scopeBindingsByOwner?: boolean;
     /**
      * Retained for 1.x source compatibility, but has no effect here:
      * `generateInlineScript()` returns a script body and creates no tag.
@@ -1755,12 +1787,24 @@ interface FieldBindingAttributes {
     readonly 'data-payload-field': string;
     readonly 'data-payload-attribute'?: string;
     readonly 'data-payload-type'?: string;
+    readonly 'data-payload-richtext'?: string;
+    readonly 'data-payload-html'?: string;
+    readonly 'data-payload-locale'?: string;
 }
 interface BindOptions {
     /** Override the bound attribute (e.g., `'src'` for `<img>`). Default: textContent. */
     readonly attribute?: string;
     /** Explicit field-type override — bypasses schema detection. */
     readonly type?: string;
+    /**
+     * Mark the binding as Lexical rich text. Usually detected automatically;
+     * set it where the initial render is empty and there is nothing to detect.
+     */
+    readonly richtext?: boolean;
+    /** Render the value as sanitised HTML rather than text. */
+    readonly html?: boolean;
+    /** Lock this element to one locale, overriding the message locale. */
+    readonly locale?: string;
 }
 /**
  * String-literal binding helper.
@@ -1795,4 +1839,90 @@ declare function bind<T = Record<string, unknown>>(field: FieldName<T>, options?
  */
 declare function bindByPath<T = Record<string, unknown>>(picker: (data: T) => unknown, options?: BindOptions): FieldBindingAttributes;
 
-export { type AnalyticsSnapshot, type BindOptions, type BlockRenderContext, type BlockRenderer, type CachedElement, type CspDirectiveMerge, type DocumentSaveHandler, type DocumentSavePluginOptions, type DocumentSaveStrategy, EventEmitter, type EventHandler, type FetchPreviewDocumentOptions, type FetchPreviewGlobalOptions, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldTransform, type FieldType, type FrameAncestorsOptions, type InlineScriptConfig, LIBRARY_PROTOCOL_VERSION, type LexicalNode, type LexicalRoot, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewPlugin, OriginDetector, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PayloadMedia, type PayloadRelationship, type PluginContext, type PluginDisposer, type PluginEvents, type PreviewFetchBaseOptions, type PreviewRequestLike, type PreviewRequestOptions, type PreviewWhere, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, buildBuiltinRenderers, buildFrameAncestors, buildScriptSrcWithNonce, createAnalyticsPlugin, debugPlugin, detectInitialLocale, documentSavePlugin, escapeHtml, escapeHtmlAttribute, fetchPreviewDocument, fetchPreviewGlobal, generateCspNonce, generateInlineScript, hasCapability, highlightPlugin, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isLexicalContent, isPreviewRequest, isSafeUrl, lexicalToHtml, lexicalToPlainText, mergeCspHeader, negotiateProtocol, registerBlockRenderer, registerBuiltinRenderer, runtimeBuildInfo, sanitizeHtml, setCspCrypto, setSanitizerDocument, wrapWithScriptTag };
+/**
+ * Authorization-gated binding emission.
+ *
+ * Binding attributes are not neutral markup. `data-payload-field` names a CMS
+ * field, and `data-payload-owner` names a global, a collection and often a
+ * document id. Emitted unconditionally they publish the shape of the content
+ * model — and the identity of documents — to every anonymous visitor and
+ * crawler of the page.
+ *
+ * The gate belongs to the application, not to this package: it is the same
+ * decision that already controls draft reads and cache policy. What this
+ * module provides is a place to apply that decision **once per request** so no
+ * individual call site can forget it, and an emission unit that cannot be
+ * partially suppressed.
+ *
+ * That second property matters more than it looks. A binding is not one
+ * attribute: a field travels with its type, its locale, its rich-text marker
+ * and its owner. Gating only the field name leaves the companions behind,
+ * which discloses the taxonomy anyway and leaves the runtime looking at a
+ * binding whose field is gone.
+ *
+ * @module @dsl/preview-bindings
+ */
+
+/** Owner marker naming the document a subtree belongs to. */
+interface OwnerBindingAttributes {
+    readonly 'data-payload-owner': string;
+}
+/**
+ * The complete absence of binding attributes.
+ *
+ * Spreading this into markup contributes nothing, which is the point: an
+ * unauthorized response must be byte-identical to one that never knew about
+ * live preview.
+ */
+type SuppressedBinding = Readonly<Record<string, never>>;
+interface PreviewBindingsOptions {
+    /**
+     * The application's own authorization verdict for this request.
+     *
+     * Never derive this from `?preview=true`, an iframe destination or a
+     * referer — those are client-controlled intent signals. Use the same
+     * verified result that decides whether drafts may be read.
+     */
+    readonly authorized: boolean;
+    /**
+     * Document this subtree belongs to, emitted as `data-payload-owner` by
+     * {@link PreviewBindings.owner}. Required only when the page previews more
+     * than one document and the runtime runs with `scopeBindingsByOwner`.
+     */
+    readonly owner?: string;
+}
+/** Request-scoped binding helpers that carry one authorization decision. */
+interface PreviewBindings {
+    /** The verdict these helpers were built with. */
+    readonly authorized: boolean;
+    /** Typed field binding, or nothing at all while unauthorized. */
+    bind: <T = Record<string, unknown>>(field: FieldName<T>, options?: BindOptions) => FieldBindingAttributes | SuppressedBinding;
+    /** Rename-safe field binding, or nothing at all while unauthorized. */
+    bindByPath: <T = Record<string, unknown>>(picker: (data: T) => unknown, options?: BindOptions) => FieldBindingAttributes | SuppressedBinding;
+    /**
+     * Owner marker for the element that owns this subtree, or nothing at all
+     * while unauthorized or when no owner was configured.
+     */
+    owner: () => OwnerBindingAttributes | SuppressedBinding;
+}
+/**
+ * Build request-scoped binding helpers around one authorization decision.
+ *
+ * ```ts
+ * const preview = createPreviewBindings({
+ *   authorized: authorization !== null,
+ *   owner: `global:${slug}`,
+ * });
+ * ```
+ * ```astro
+ * <section {...preview.owner()}>
+ *   <h1 {...preview.bind<Homepage>('heroTitle')}>{data.heroTitle}</h1>
+ * </section>
+ * ```
+ *
+ * While unauthorized every helper returns an empty attribute set, so the
+ * public response carries no `data-payload-*` at all.
+ */
+declare function createPreviewBindings(options: PreviewBindingsOptions): PreviewBindings;
+
+export { type AnalyticsSnapshot, type BindOptions, type BlockRenderContext, type BlockRenderer, type CachedElement, type CspDirectiveMerge, type DocumentSaveHandler, type DocumentSavePluginOptions, type DocumentSaveStrategy, EventEmitter, type EventHandler, type FetchPreviewDocumentOptions, type FetchPreviewGlobalOptions, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldTransform, type FieldType, type FrameAncestorsOptions, type InlineScriptConfig, LIBRARY_PROTOCOL_VERSION, type LexicalNode, type LexicalRoot, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewPlugin, OriginDetector, type OwnerBindingAttributes, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PayloadMedia, type PayloadRelationship, type PluginContext, type PluginDisposer, type PluginEvents, type PreviewBindings, type PreviewBindingsOptions, type PreviewFetchBaseOptions, type PreviewRequestLike, type PreviewRequestOptions, type PreviewWhere, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type SuppressedBinding, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, buildBuiltinRenderers, buildFrameAncestors, buildScriptSrcWithNonce, createAnalyticsPlugin, createPreviewBindings, debugPlugin, detectInitialLocale, documentSavePlugin, escapeHtml, escapeHtmlAttribute, fetchPreviewDocument, fetchPreviewGlobal, generateCspNonce, generateInlineScript, hasCapability, highlightPlugin, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isLexicalContent, isPreviewRequest, isSafeUrl, lexicalToHtml, lexicalToPlainText, mergeCspHeader, negotiateProtocol, registerBlockRenderer, registerBuiltinRenderer, runtimeBuildInfo, sanitizeHtml, setCspCrypto, setSanitizerDocument, wrapWithScriptTag };

package/dist/index.d.ts

@@ -379,6 +379,15 @@ interface CachedElement {
     readonly arraySeparator?: string;
     /** Optional locale code locked onto this element (overrides the global locale). */
     readonly locale?: string;
+    /**
+     * Optional document this binding belongs to, resolved from the nearest
+     * `data-payload-owner` ancestor (the element itself included).
+     *
+     * Only consulted while owner scoping is enabled. Without it a field name is
+     * the sole identity, so every document rendered on the page competes for the
+     * same name.
+     */
+    readonly owner?: string;
 }
 /**
  * Context passed to every field renderer. Provides access to the
@@ -550,6 +559,20 @@ interface LivePreviewClientConfig {
     readonly heartbeatMs?: number;
     /** IntersectionObserver rootMargin. Defaults to `200px`. */
     readonly intersectionRootMargin?: string;
+    /**
+     * Restrict each update to the bindings owned by the document it describes.
+     *
+     * Ownership is declared in markup with `data-payload-owner`, resolved from
+     * the nearest ancestor: `global:<slug>`, `collection:<slug>`, or
+     * `collection:<slug>:<id>`. Payload already sends the edited document's
+     * identity, so nothing else needs configuring.
+     *
+     * Defaults to `false`, which keeps the 1.x behaviour of matching on the
+     * field name alone. Enable it when one page previews more than one document
+     * and a field name is therefore no longer a unique identity. While enabled,
+     * a binding without an owner is never updated.
+     */
+    readonly scopeBindingsByOwner?: boolean;
     /** Bypass the visibility gate (apply every update). Defaults to `false`. */
     readonly disableVisibilityGate?: boolean;
     /** Cache-size threshold above which off-screen updates are queued for replay. Defaults to 50. */
@@ -721,6 +744,15 @@ interface InlineScriptConfig {
      * a production-like origin list. Default `false`.
      */
     readonly disableLocalhostMatching?: boolean;
+    /**
+     * Restrict each update to the bindings owned by the document it describes,
+     * declared in markup with `data-payload-owner` and resolved from the nearest
+     * ancestor. Default `false`, which keeps matching on the field name alone.
+     *
+     * Enable it when one page previews more than one document. While enabled a
+     * binding without an owner is never updated.
+     */
+    readonly scopeBindingsByOwner?: boolean;
     /**
      * Retained for 1.x source compatibility, but has no effect here:
      * `generateInlineScript()` returns a script body and creates no tag.
@@ -1755,12 +1787,24 @@ interface FieldBindingAttributes {
     readonly 'data-payload-field': string;
     readonly 'data-payload-attribute'?: string;
     readonly 'data-payload-type'?: string;
+    readonly 'data-payload-richtext'?: string;
+    readonly 'data-payload-html'?: string;
+    readonly 'data-payload-locale'?: string;
 }
 interface BindOptions {
     /** Override the bound attribute (e.g., `'src'` for `<img>`). Default: textContent. */
     readonly attribute?: string;
     /** Explicit field-type override — bypasses schema detection. */
     readonly type?: string;
+    /**
+     * Mark the binding as Lexical rich text. Usually detected automatically;
+     * set it where the initial render is empty and there is nothing to detect.
+     */
+    readonly richtext?: boolean;
+    /** Render the value as sanitised HTML rather than text. */
+    readonly html?: boolean;
+    /** Lock this element to one locale, overriding the message locale. */
+    readonly locale?: string;
 }
 /**
  * String-literal binding helper.
@@ -1795,4 +1839,90 @@ declare function bind<T = Record<string, unknown>>(field: FieldName<T>, options?
  */
 declare function bindByPath<T = Record<string, unknown>>(picker: (data: T) => unknown, options?: BindOptions): FieldBindingAttributes;
 
-export { type AnalyticsSnapshot, type BindOptions, type BlockRenderContext, type BlockRenderer, type CachedElement, type CspDirectiveMerge, type DocumentSaveHandler, type DocumentSavePluginOptions, type DocumentSaveStrategy, EventEmitter, type EventHandler, type FetchPreviewDocumentOptions, type FetchPreviewGlobalOptions, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldTransform, type FieldType, type FrameAncestorsOptions, type InlineScriptConfig, LIBRARY_PROTOCOL_VERSION, type LexicalNode, type LexicalRoot, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewPlugin, OriginDetector, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PayloadMedia, type PayloadRelationship, type PluginContext, type PluginDisposer, type PluginEvents, type PreviewFetchBaseOptions, type PreviewRequestLike, type PreviewRequestOptions, type PreviewWhere, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, buildBuiltinRenderers, buildFrameAncestors, buildScriptSrcWithNonce, createAnalyticsPlugin, debugPlugin, detectInitialLocale, documentSavePlugin, escapeHtml, escapeHtmlAttribute, fetchPreviewDocument, fetchPreviewGlobal, generateCspNonce, generateInlineScript, hasCapability, highlightPlugin, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isLexicalContent, isPreviewRequest, isSafeUrl, lexicalToHtml, lexicalToPlainText, mergeCspHeader, negotiateProtocol, registerBlockRenderer, registerBuiltinRenderer, runtimeBuildInfo, sanitizeHtml, setCspCrypto, setSanitizerDocument, wrapWithScriptTag };
+/**
+ * Authorization-gated binding emission.
+ *
+ * Binding attributes are not neutral markup. `data-payload-field` names a CMS
+ * field, and `data-payload-owner` names a global, a collection and often a
+ * document id. Emitted unconditionally they publish the shape of the content
+ * model — and the identity of documents — to every anonymous visitor and
+ * crawler of the page.
+ *
+ * The gate belongs to the application, not to this package: it is the same
+ * decision that already controls draft reads and cache policy. What this
+ * module provides is a place to apply that decision **once per request** so no
+ * individual call site can forget it, and an emission unit that cannot be
+ * partially suppressed.
+ *
+ * That second property matters more than it looks. A binding is not one
+ * attribute: a field travels with its type, its locale, its rich-text marker
+ * and its owner. Gating only the field name leaves the companions behind,
+ * which discloses the taxonomy anyway and leaves the runtime looking at a
+ * binding whose field is gone.
+ *
+ * @module @dsl/preview-bindings
+ */
+
+/** Owner marker naming the document a subtree belongs to. */
+interface OwnerBindingAttributes {
+    readonly 'data-payload-owner': string;
+}
+/**
+ * The complete absence of binding attributes.
+ *
+ * Spreading this into markup contributes nothing, which is the point: an
+ * unauthorized response must be byte-identical to one that never knew about
+ * live preview.
+ */
+type SuppressedBinding = Readonly<Record<string, never>>;
+interface PreviewBindingsOptions {
+    /**
+     * The application's own authorization verdict for this request.
+     *
+     * Never derive this from `?preview=true`, an iframe destination or a
+     * referer — those are client-controlled intent signals. Use the same
+     * verified result that decides whether drafts may be read.
+     */
+    readonly authorized: boolean;
+    /**
+     * Document this subtree belongs to, emitted as `data-payload-owner` by
+     * {@link PreviewBindings.owner}. Required only when the page previews more
+     * than one document and the runtime runs with `scopeBindingsByOwner`.
+     */
+    readonly owner?: string;
+}
+/** Request-scoped binding helpers that carry one authorization decision. */
+interface PreviewBindings {
+    /** The verdict these helpers were built with. */
+    readonly authorized: boolean;
+    /** Typed field binding, or nothing at all while unauthorized. */
+    bind: <T = Record<string, unknown>>(field: FieldName<T>, options?: BindOptions) => FieldBindingAttributes | SuppressedBinding;
+    /** Rename-safe field binding, or nothing at all while unauthorized. */
+    bindByPath: <T = Record<string, unknown>>(picker: (data: T) => unknown, options?: BindOptions) => FieldBindingAttributes | SuppressedBinding;
+    /**
+     * Owner marker for the element that owns this subtree, or nothing at all
+     * while unauthorized or when no owner was configured.
+     */
+    owner: () => OwnerBindingAttributes | SuppressedBinding;
+}
+/**
+ * Build request-scoped binding helpers around one authorization decision.
+ *
+ * ```ts
+ * const preview = createPreviewBindings({
+ *   authorized: authorization !== null,
+ *   owner: `global:${slug}`,
+ * });
+ * ```
+ * ```astro
+ * <section {...preview.owner()}>
+ *   <h1 {...preview.bind<Homepage>('heroTitle')}>{data.heroTitle}</h1>
+ * </section>
+ * ```
+ *
+ * While unauthorized every helper returns an empty attribute set, so the
+ * public response carries no `data-payload-*` at all.
+ */
+declare function createPreviewBindings(options: PreviewBindingsOptions): PreviewBindings;
+
+export { type AnalyticsSnapshot, type BindOptions, type BlockRenderContext, type BlockRenderer, type CachedElement, type CspDirectiveMerge, type DocumentSaveHandler, type DocumentSavePluginOptions, type DocumentSaveStrategy, EventEmitter, type EventHandler, type FetchPreviewDocumentOptions, type FetchPreviewGlobalOptions, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldTransform, type FieldType, type FrameAncestorsOptions, type InlineScriptConfig, LIBRARY_PROTOCOL_VERSION, type LexicalNode, type LexicalRoot, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewPlugin, OriginDetector, type OwnerBindingAttributes, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PayloadMedia, type PayloadRelationship, type PluginContext, type PluginDisposer, type PluginEvents, type PreviewBindings, type PreviewBindingsOptions, type PreviewFetchBaseOptions, type PreviewRequestLike, type PreviewRequestOptions, type PreviewWhere, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type SuppressedBinding, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, buildBuiltinRenderers, buildFrameAncestors, buildScriptSrcWithNonce, createAnalyticsPlugin, createPreviewBindings, debugPlugin, detectInitialLocale, documentSavePlugin, escapeHtml, escapeHtmlAttribute, fetchPreviewDocument, fetchPreviewGlobal, generateCspNonce, generateInlineScript, hasCapability, highlightPlugin, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isLexicalContent, isPreviewRequest, isSafeUrl, lexicalToHtml, lexicalToPlainText, mergeCspHeader, negotiateProtocol, registerBlockRenderer, registerBuiltinRenderer, runtimeBuildInfo, sanitizeHtml, setCspCrypto, setSanitizerDocument, wrapWithScriptTag };