payload-live-preview 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -1787,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.
@@ -1827,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

@@ -1787,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.
@@ -1827,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 };