payload-live-preview 2.3.1 → 2.4.0

package/dist/core.d.cts

@@ -1603,7 +1603,7 @@ interface DocumentSessionOptions {
     /**
      * Milliseconds a merge may wait for the server; after that the update is `unavailable`
      * and `data` stays the last good document. Off by default: a merge waits as long as the
-     * server takes.
+     * server takes. `0` keeps it off when 3.0 gives it a default (ADR 0007, row 27).
      */
     readonly timeoutMs?: number;
     /**
@@ -1623,28 +1623,36 @@ interface DocumentSessionOptions {
      * slug, and a create screen has no id yet. Without it the session merges every update.
      */
     readonly document?: PreviewDocument;
+    /**
+     * With a `locale` in `document`, also leave alone an update that names no locale, as 3.0
+     * does for every hook with a `locale` (ADR 0007, row 31). Off by default: such an update is
+     * merged.
+     */
+    readonly requireLocale?: boolean;
     /** Injected for tests. */
     readonly fetchFn?: typeof fetch;
     /** Window to listen on. Default the global one. */
     readonly target?: Window;
 }
-type Listener = () => void;
-declare class DocumentSession<T> {
-    #private;
-    constructor(initialData: T, options: DocumentSessionOptions);
+/**
+ * One preview document, with no framework around it: `subscribe` and `getSnapshot`
+ * fit a `useSyncExternalStore` or a Svelte store. `createDocumentSession()` makes
+ * one; no entry exports the class behind it.
+ * @beta
+ */
+interface DocumentSession<T> {
     /**
-     * Attach on the first subscriber and detach with the last, so a component
-     * that mounts twice (React's strict mode) listens once and a page that
-     * unmounts the hook stops listening at all.
+     * Called with every new snapshot. The first listener starts listening for the
+     * admin's messages, and the last one to unsubscribe stops it.
      */
-    subscribe: (listener: Listener) => (() => void);
-    getSnapshot: () => DocumentSnapshot<T>;
+    readonly subscribe: (listener: () => void) => () => void;
+    /** The current snapshot; a new object only when something in it changed. */
+    readonly getSnapshot: () => DocumentSnapshot<T>;
     /** Server rendering has no window and no messages: the initial snapshot a client render starts from. */
-    getServerSnapshot: () => DocumentSnapshot<T>;
+    readonly getServerSnapshot: () => DocumentSnapshot<T>;
 }
 /**
- * One preview document, with no framework around it: `subscribe` and `getSnapshot`
- * fit a `useSyncExternalStore` or a Svelte store.
+ * A session for one preview document. Nothing listens before the first `subscribe`.
  * @beta
  */
 declare function createDocumentSession<T>(initialData: T, options: DocumentSessionOptions): DocumentSession<T>;
@@ -1671,4 +1679,4 @@ declare function createDocumentSession<T>(initialData: T, options: DocumentSessi
 /** @internal */
 declare const CORE_ENTRY = true;
 
-export { AUTHORIZED_PREVIEW_BRAND_KEY, type AuthorizedPreviewContext, type AuthorizedPreviewDocument, type AuthorizedPreviewPayloadScope, type AuthorizedPreviewScope, type BindOptions, CAPABILITY_DECLARATIONS, CAPABILITY_DOCUMENTATION, CORE_ENTRY, type CachedElement, type CapabilityDeclaration, type CapabilityDocumentation, type CapabilitySource, type ConnectionStatus, type CustomRendererKey, DIAGNOSTIC_CODES, type DefaultsProfile, type DiagnosticCode, DocumentSession, type DocumentSessionOptions, type DocumentSnapshot, type DocumentStatus, EventEmitter, type EventHandler, type EventSourcePolicy, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldType, type FragmentBoundaryAttributes, type FragmentBoundaryOptions, type FragmentContext, type FragmentReport, type FragmentStrategy, type FrameAncestorsOptions, ISLAND_EVENT, type InspectionBindings, type InspectionFidelity, type InspectionFragments, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionRoute, type InspectionScheduler, type IslandUpdateDetail, LIBRARY_PROTOCOL_VERSION, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, OriginDetector, type OwnerBindingAttributes, PROTOCOL_CAPABILITIES, type PayloadDocumentEventDetail, type PayloadFieldCondition, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PluginCompatibility, type PluginInspection, type PreviewAuthorizationStrategyName, type PreviewBindings, type PreviewBindingsOptions, type PreviewDocument, type ProtocolCapability, type ProtocolNegotiation, type ProtocolProfile, type ProtocolProfileName, type RenderContext, type RendererKey, type RevisionDisplay, type RevisionDisplayState, type RevisionShortfall, type RichTextRenderer, type RouteContext, type RouteOutcome, type RoutePlanContext, type RouteRefresh, type RouteStrategy, type SanitizerDocument, type SanitizerPolicyMode, type StrategyHandlers, type SuppressedBinding, type Unsubscribe, type UpdateSource, VERSION, type ValueAt, bind, bindByPath, buildFrameAncestors, buildScriptSrcWithNonce, createDocumentSession, createPreviewBindings, detectInitialLocale, detectProtocolProfile, escapeHtml, escapeHtmlAttribute, generateCspNonce, hasCapability, initLivePreview, isAuthorizedPreviewContext, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isInsideIsland, isSafeUrl, negotiateProtocol, registerRouteRefresh, sanitizeHtml, setCspCrypto, setSanitizerDocument };
+export { AUTHORIZED_PREVIEW_BRAND_KEY, type AuthorizedPreviewContext, type AuthorizedPreviewDocument, type AuthorizedPreviewPayloadScope, type AuthorizedPreviewScope, type BindOptions, CAPABILITY_DECLARATIONS, CAPABILITY_DOCUMENTATION, CORE_ENTRY, type CachedElement, type CapabilityDeclaration, type CapabilityDocumentation, type CapabilitySource, type ConnectionStatus, type CustomRendererKey, DIAGNOSTIC_CODES, type DefaultsProfile, type DiagnosticCode, type DocumentSession, type DocumentSessionOptions, type DocumentSnapshot, type DocumentStatus, EventEmitter, type EventHandler, type EventSourcePolicy, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldType, type FragmentBoundaryAttributes, type FragmentBoundaryOptions, type FragmentContext, type FragmentReport, type FragmentStrategy, type FrameAncestorsOptions, ISLAND_EVENT, type InspectionBindings, type InspectionFidelity, type InspectionFragments, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionRoute, type InspectionScheduler, type IslandUpdateDetail, LIBRARY_PROTOCOL_VERSION, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, OriginDetector, type OwnerBindingAttributes, PROTOCOL_CAPABILITIES, type PayloadDocumentEventDetail, type PayloadFieldCondition, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PluginCompatibility, type PluginInspection, type PreviewAuthorizationStrategyName, type PreviewBindings, type PreviewBindingsOptions, type PreviewDocument, type ProtocolCapability, type ProtocolNegotiation, type ProtocolProfile, type ProtocolProfileName, type RenderContext, type RendererKey, type RevisionDisplay, type RevisionDisplayState, type RevisionShortfall, type RichTextRenderer, type RouteContext, type RouteOutcome, type RoutePlanContext, type RouteRefresh, type RouteStrategy, type SanitizerDocument, type SanitizerPolicyMode, type StrategyHandlers, type SuppressedBinding, type Unsubscribe, type UpdateSource, VERSION, type ValueAt, bind, bindByPath, buildFrameAncestors, buildScriptSrcWithNonce, createDocumentSession, createPreviewBindings, detectInitialLocale, detectProtocolProfile, escapeHtml, escapeHtmlAttribute, generateCspNonce, hasCapability, initLivePreview, isAuthorizedPreviewContext, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isInsideIsland, isSafeUrl, negotiateProtocol, registerRouteRefresh, sanitizeHtml, setCspCrypto, setSanitizerDocument };

package/dist/core.d.ts

@@ -1603,7 +1603,7 @@ interface DocumentSessionOptions {
     /**
      * Milliseconds a merge may wait for the server; after that the update is `unavailable`
      * and `data` stays the last good document. Off by default: a merge waits as long as the
-     * server takes.
+     * server takes. `0` keeps it off when 3.0 gives it a default (ADR 0007, row 27).
      */
     readonly timeoutMs?: number;
     /**
@@ -1623,28 +1623,36 @@ interface DocumentSessionOptions {
      * slug, and a create screen has no id yet. Without it the session merges every update.
      */
     readonly document?: PreviewDocument;
+    /**
+     * With a `locale` in `document`, also leave alone an update that names no locale, as 3.0
+     * does for every hook with a `locale` (ADR 0007, row 31). Off by default: such an update is
+     * merged.
+     */
+    readonly requireLocale?: boolean;
     /** Injected for tests. */
     readonly fetchFn?: typeof fetch;
     /** Window to listen on. Default the global one. */
     readonly target?: Window;
 }
-type Listener = () => void;
-declare class DocumentSession<T> {
-    #private;
-    constructor(initialData: T, options: DocumentSessionOptions);
+/**
+ * One preview document, with no framework around it: `subscribe` and `getSnapshot`
+ * fit a `useSyncExternalStore` or a Svelte store. `createDocumentSession()` makes
+ * one; no entry exports the class behind it.
+ * @beta
+ */
+interface DocumentSession<T> {
     /**
-     * Attach on the first subscriber and detach with the last, so a component
-     * that mounts twice (React's strict mode) listens once and a page that
-     * unmounts the hook stops listening at all.
+     * Called with every new snapshot. The first listener starts listening for the
+     * admin's messages, and the last one to unsubscribe stops it.
      */
-    subscribe: (listener: Listener) => (() => void);
-    getSnapshot: () => DocumentSnapshot<T>;
+    readonly subscribe: (listener: () => void) => () => void;
+    /** The current snapshot; a new object only when something in it changed. */
+    readonly getSnapshot: () => DocumentSnapshot<T>;
     /** Server rendering has no window and no messages: the initial snapshot a client render starts from. */
-    getServerSnapshot: () => DocumentSnapshot<T>;
+    readonly getServerSnapshot: () => DocumentSnapshot<T>;
 }
 /**
- * One preview document, with no framework around it: `subscribe` and `getSnapshot`
- * fit a `useSyncExternalStore` or a Svelte store.
+ * A session for one preview document. Nothing listens before the first `subscribe`.
  * @beta
  */
 declare function createDocumentSession<T>(initialData: T, options: DocumentSessionOptions): DocumentSession<T>;
@@ -1671,4 +1679,4 @@ declare function createDocumentSession<T>(initialData: T, options: DocumentSessi
 /** @internal */
 declare const CORE_ENTRY = true;
 
-export { AUTHORIZED_PREVIEW_BRAND_KEY, type AuthorizedPreviewContext, type AuthorizedPreviewDocument, type AuthorizedPreviewPayloadScope, type AuthorizedPreviewScope, type BindOptions, CAPABILITY_DECLARATIONS, CAPABILITY_DOCUMENTATION, CORE_ENTRY, type CachedElement, type CapabilityDeclaration, type CapabilityDocumentation, type CapabilitySource, type ConnectionStatus, type CustomRendererKey, DIAGNOSTIC_CODES, type DefaultsProfile, type DiagnosticCode, DocumentSession, type DocumentSessionOptions, type DocumentSnapshot, type DocumentStatus, EventEmitter, type EventHandler, type EventSourcePolicy, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldType, type FragmentBoundaryAttributes, type FragmentBoundaryOptions, type FragmentContext, type FragmentReport, type FragmentStrategy, type FrameAncestorsOptions, ISLAND_EVENT, type InspectionBindings, type InspectionFidelity, type InspectionFragments, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionRoute, type InspectionScheduler, type IslandUpdateDetail, LIBRARY_PROTOCOL_VERSION, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, OriginDetector, type OwnerBindingAttributes, PROTOCOL_CAPABILITIES, type PayloadDocumentEventDetail, type PayloadFieldCondition, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PluginCompatibility, type PluginInspection, type PreviewAuthorizationStrategyName, type PreviewBindings, type PreviewBindingsOptions, type PreviewDocument, type ProtocolCapability, type ProtocolNegotiation, type ProtocolProfile, type ProtocolProfileName, type RenderContext, type RendererKey, type RevisionDisplay, type RevisionDisplayState, type RevisionShortfall, type RichTextRenderer, type RouteContext, type RouteOutcome, type RoutePlanContext, type RouteRefresh, type RouteStrategy, type SanitizerDocument, type SanitizerPolicyMode, type StrategyHandlers, type SuppressedBinding, type Unsubscribe, type UpdateSource, VERSION, type ValueAt, bind, bindByPath, buildFrameAncestors, buildScriptSrcWithNonce, createDocumentSession, createPreviewBindings, detectInitialLocale, detectProtocolProfile, escapeHtml, escapeHtmlAttribute, generateCspNonce, hasCapability, initLivePreview, isAuthorizedPreviewContext, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isInsideIsland, isSafeUrl, negotiateProtocol, registerRouteRefresh, sanitizeHtml, setCspCrypto, setSanitizerDocument };
+export { AUTHORIZED_PREVIEW_BRAND_KEY, type AuthorizedPreviewContext, type AuthorizedPreviewDocument, type AuthorizedPreviewPayloadScope, type AuthorizedPreviewScope, type BindOptions, CAPABILITY_DECLARATIONS, CAPABILITY_DOCUMENTATION, CORE_ENTRY, type CachedElement, type CapabilityDeclaration, type CapabilityDocumentation, type CapabilitySource, type ConnectionStatus, type CustomRendererKey, DIAGNOSTIC_CODES, type DefaultsProfile, type DiagnosticCode, type DocumentSession, type DocumentSessionOptions, type DocumentSnapshot, type DocumentStatus, EventEmitter, type EventHandler, type EventSourcePolicy, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldType, type FragmentBoundaryAttributes, type FragmentBoundaryOptions, type FragmentContext, type FragmentReport, type FragmentStrategy, type FrameAncestorsOptions, ISLAND_EVENT, type InspectionBindings, type InspectionFidelity, type InspectionFragments, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionRoute, type InspectionScheduler, type IslandUpdateDetail, LIBRARY_PROTOCOL_VERSION, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, OriginDetector, type OwnerBindingAttributes, PROTOCOL_CAPABILITIES, type PayloadDocumentEventDetail, type PayloadFieldCondition, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PluginCompatibility, type PluginInspection, type PreviewAuthorizationStrategyName, type PreviewBindings, type PreviewBindingsOptions, type PreviewDocument, type ProtocolCapability, type ProtocolNegotiation, type ProtocolProfile, type ProtocolProfileName, type RenderContext, type RendererKey, type RevisionDisplay, type RevisionDisplayState, type RevisionShortfall, type RichTextRenderer, type RouteContext, type RouteOutcome, type RoutePlanContext, type RouteRefresh, type RouteStrategy, type SanitizerDocument, type SanitizerPolicyMode, type StrategyHandlers, type SuppressedBinding, type Unsubscribe, type UpdateSource, VERSION, type ValueAt, bind, bindByPath, buildFrameAncestors, buildScriptSrcWithNonce, createDocumentSession, createPreviewBindings, detectInitialLocale, detectProtocolProfile, escapeHtml, escapeHtmlAttribute, generateCspNonce, hasCapability, initLivePreview, isAuthorizedPreviewContext, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isInsideIsland, isSafeUrl, negotiateProtocol, registerRouteRefresh, sanitizeHtml, setCspCrypto, setSanitizerDocument };