@atlaskit/editor-synced-block-provider 8.5.7 → 8.6.1

package/dist/types/store-manager/sourceSyncBlockStoreManager.d.ts

@@ -3,6 +3,7 @@ import type { ViewMode } from '@atlaskit/editor-plugin-editor-viewmode';
 import type { Node as PMNode } from '@atlaskit/editor-prosemirror/model';
 import type { ResourceId, SyncBlockAttrs, BlockInstanceId, DeletionReason, DeletionMechanism, ReferenceSyncBlockData } from '../common/types';
 import type { SyncBlockDataProviderInterface, SyncBlockSourceInfo } from '../providers/types';
+import type { CreateSuccessEnrichment } from '../utils/errorHandling';
 export type ConfirmationCallback = (syncBlockIds: SyncBlockAttrs[], deleteReason: DeletionReason | undefined) => Promise<boolean>;
 type OnDelete = () => void;
 type OnCompletion = (success: boolean) => void;
@@ -35,6 +36,20 @@ export declare class SourceSyncBlockStoreManager {
      * multiple blocks are created concurrently. See EDITOR-7112.
      */
     private creationsTimedOutDuringFlush;
+    /**
+     * Creation-type signals captured at `createBodiedSyncBlockNode` time and read
+     * back in `commitPendingCreation` to enrich the `syncedBlockCreate` event.
+     * Kept out of the flushed cache record so it never leaks into Block Service /
+     * ADF; removed once consumed.
+     */
+    private creationEnrichment;
+    /**
+     * Resource IDs of blocks created empty this session that have not yet fired
+     * the first-content-added event. Added on empty creation, removed when the
+     * block first gains content (the event fires once). Blocks created with
+     * content or not created this session are never tracked.
+     */
+    private awaitingFirstContent;
     private createExperience;
     private saveExperience;
     private deleteExperience;
@@ -86,6 +101,13 @@ export declare class SourceSyncBlockStoreManager {
      * @param success
      */
     commitPendingCreation(success: boolean, resourceId: ResourceId): void;
+    /**
+     * Fire the first-content-added event once when a block created empty this
+     * session first gains content. The caller detects the in-block edit; this owns
+     * dedupe + emission (fires at most once per block, only for empty→content).
+     * Gated behind `platform_editor_blocks_patch_4`.
+     */
+    maybeEmitFirstContentAdded(resourceId: ResourceId, blockInstanceId?: BlockInstanceId): void;
     registerConfirmationCallback(callback: ConfirmationCallback): () => void;
     requireConfirmationBeforeDelete(): boolean;
     /**
@@ -97,8 +119,12 @@ export declare class SourceSyncBlockStoreManager {
      * @param attrs attributes Ids of the node
      * @param node the ProseMirror node to cache
      * @param onCompletion callback invoked when creation completes
+     * @param enrichment optional creation-type signals stashed and attached to the
+     *   `syncedBlockCreate` event when the async create resolves. When
+     *   `createdEmpty` is true the block is also registered for the
+     *   first-content-added event.
      */
-    createBodiedSyncBlockNode(attrs: SyncBlockAttrs, node: PMNode, onCompletion: OnCompletion): void;
+    createBodiedSyncBlockNode(attrs: SyncBlockAttrs, node: PMNode, onCompletion: OnCompletion, enrichment?: CreateSuccessEnrichment): void;
     private setPendingDeletion;
     /**
      * Drop dedupe entries older than {@link DELETE_DEDUPE_WINDOW_MS} so

package/dist/types/store-manager/syncBlockSubscriptionManager.d.ts

@@ -37,6 +37,12 @@ export declare class SyncBlockSubscriptionManager {
     private static readonly MAX_RETRY_DELAY_MS;
     private retryAttempts;
     private pendingRetries;
+    private deferredExhausted;
+    private static readonly WAKE_DEBOUNCE_MS;
+    private wakeDebounceTimer;
+    private readonly onOnline;
+    private readonly onVisibilityChange;
+    private wakeListenerCleanups;
     private getMaxRetryAttempts;
     private getReconnectionDelay;
     constructor(deps: SyncBlockSubscriptionManagerDeps);
@@ -72,6 +78,28 @@ export declare class SyncBlockSubscriptionManager {
      * update is received, indicating the subscription is healthy.
      */
     private resetRetryCount;
+    /**
+     * Whether the tab is currently hidden. SSR/non-browser is treated as "not hidden" so
+     * we never defer where wake events can't fire (realtime never subscribes there anyway).
+     */
+    private isDocumentHidden;
+    /**
+     * Lazily register shared `online` / `visibilitychange` listeners on first deferral.
+     * Torn down by `unregisterWakeListeners` (via `handleWake`). No-op in SSR / non-browser.
+     */
+    private registerWakeListeners;
+    private unregisterWakeListeners;
+    /**
+     * Coalesce a burst of wake events into one debounced re-arm sweep. Callers decide
+     * eligibility: `onOnline` always sweeps; `onVisibilityChange` only sweeps when visible.
+     */
+    private scheduleWakeSweep;
+    /**
+     * Re-arm every deferred resource: full reset (attempts→0) + immediate reconnect now
+     * the tab is visible / online. Healthy subscriptions are untouched. A re-armed cycle
+     * that later exhausts while visible fires the terminal error normally.
+     */
+    private handleWake;
     private cancelPendingRetry;
     private cancelAllPendingRetries;
     cleanupSubscription(resourceId: ResourceId): void;

package/dist/types/utils/errorHandling.d.ts

@@ -1,5 +1,5 @@
 import { ACTION, ACTION_SUBJECT, ACTION_SUBJECT_ID } from '@atlaskit/editor-common/analytics';
-import type { RendererSyncBlockEventPayload, OperationalAEP, SyncBlockEventPayload } from '@atlaskit/editor-common/analytics';
+import type { INPUT_METHOD, RendererSyncBlockEventPayload, OperationalAEP, SyncBlockEventPayload } from '@atlaskit/editor-common/analytics';
 import { SyncBlockError } from '../common/types';
 import type { DeletionMechanism, DeletionReason } from '../common/types';
 export declare const stringifyError: (error: unknown) => string | undefined;
@@ -111,6 +111,13 @@ export type FetchErrorAttributionAttributes = {
      * always sets it, so requiring it costs nothing.
      */
     benign: boolean;
+    /**
+     * Set when a `websocket_exhausted` outcome was deferred (tab hidden at exhaustion, so
+     * the subscription re-arms on online/visibilitychange) rather than surfaced as a
+     * terminal failure. Auditable on the dashboard but counted benign — the user isn't
+     * experiencing a failure while hidden. Spread only when true, never `undefined`.
+     */
+    deferred?: boolean;
 };
 /**
  * Builds the {@link FetchErrorAttributionAttributes} for a failed fetch/subscribe
@@ -122,7 +129,7 @@ export type FetchErrorAttributionAttributes = {
  * `gateEnabled` is injected by the caller (the store managers evaluate `fg(...)`) so this
  * helper stays pure and trivially unit-testable for both gate states.
  */
-export declare const buildFetchErrorAttribution: (gateEnabled: boolean, error?: string, statusCode?: number) => FetchErrorAttributionAttributes | undefined;
+export declare const buildFetchErrorAttribution: (gateEnabled: boolean, error?: string, statusCode?: number, deferred?: boolean) => FetchErrorAttributionAttributes | undefined;
 /**
  * Shared operational ERROR payload builder for synced-block events.
  *
@@ -141,6 +148,7 @@ export declare function getErrorPayload<T extends ACTION_SUBJECT_ID>(actionSubje
     reason?: SyncBlockFetchErrorReason;
     statusCode?: number;
     benign?: boolean;
+    deferred?: boolean;
 }>;
 export declare function getErrorPayload<T extends ACTION_SUBJECT_ID>(actionSubjectId: T, error: string, resourceId?: string, sourceProduct?: string, attribution?: ErrorAttributionAttributes): OperationalAEP<ACTION.ERROR, ACTION_SUBJECT.SYNCED_BLOCK, T, {
     error: string;
@@ -175,11 +183,28 @@ export declare const fetchReferencesErrorPayload: (error: string, resourceId?: s
 export declare const fetchSuccessPayload: (resourceId: string, blockInstanceId?: string, sourceProduct?: string) => RendererSyncBlockEventPayload;
 export declare const createSuccessPayload: (resourceId: string, sourceProduct?: string) => SyncBlockEventPayload;
 /**
- * Operational `syncedBlockCreate` success event (previously only error rows
- * existed, so dashboards had no create denominator). Fired behind
- * `platform_editor_blocks_patch_4` with the `blockInstanceId` join key.
+ * Optional enrichment for the `syncedBlockCreate` success event. All fields
+ * optional so gate-off/legacy payloads are unchanged. `inputMethod`: creating
+ * surface (enum, PII-safe). `createdEmpty`: true from an empty selection, false
+ * when content was converted.
+ */
+export type CreateSuccessEnrichment = {
+    createdEmpty?: boolean;
+    inputMethod?: INPUT_METHOD;
+};
+/**
+ * Operational `syncedBlockCreate` success event, behind
+ * `platform_editor_blocks_patch_4`, with the `blockInstanceId` join key and,
+ * when available, the `inputMethod` + `createdEmpty` creation-type signals.
+ */
+export declare const createSuccessOperationalPayload: (resourceId: string, blockInstanceId?: string, sourceProduct?: string, enrichment?: CreateSuccessEnrichment) => SyncBlockEventPayload;
+/**
+ * Operational first-content-added event, behind
+ * `platform_editor_blocks_patch_4`. Fired once when a block created empty first
+ * gains user content. Join keys only (`resourceId` + `blockInstanceId`), no user
+ * content (PII-safe).
  */
-export declare const createSuccessOperationalPayload: (resourceId: string, blockInstanceId?: string, sourceProduct?: string) => SyncBlockEventPayload;
+export declare const addContentSuccessPayload: (resourceId: string, blockInstanceId?: string, sourceProduct?: string) => SyncBlockEventPayload;
 export declare const updateSuccessPayload: (resourceId: string, hasReference?: boolean, sourceProduct?: string) => SyncBlockEventPayload;
 /**
  * Optional enrichment for the `syncedBlockDelete` success event behind

package/package.json

@@ -17,20 +17,22 @@
 	"atlaskit:src": "src/index.ts",
 	"dependencies": {
 		"@atlaskit/adf-utils": "^20.3.0",
+		"@atlaskit/browser-apis": "^1.1.0",
 		"@atlaskit/editor-json-transformer": "^9.0.0",
 		"@atlaskit/editor-prosemirror": "^8.0.0",
 		"@atlaskit/node-data-provider": "^13.0.0",
 		"@atlaskit/platform-feature-flags": "^2.0.0",
-		"@atlaskit/tmp-editor-statsig": "^124.0.0",
+		"@atlaskit/tmp-editor-statsig": "^124.2.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^0.20.0",
+		"bind-event-listener": "^3.0.0",
 		"graphql-ws": "^5.14.2",
 		"lodash": "^4.17.21",
 		"raf-schd": "^4.0.3",
 		"uuid": "^3.1.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^116.24.0",
+		"@atlaskit/editor-common": "^116.27.0",
 		"react": "^18.2.0"
 	},
 	"devDependencies": {
@@ -74,7 +76,7 @@
 		}
 	},
 	"name": "@atlaskit/editor-synced-block-provider",
-	"version": "8.5.7",
+	"version": "8.6.1",
 	"description": "Synced Block Provider for @atlaskit/editor-plugin-synced-block",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -82,9 +84,6 @@
 		"registry": "https://registry.npmjs.org/"
 	},
 	"platform-feature-flags": {
-		"platform_editor_blocks_patch_2": {
-			"type": "boolean"
-		},
 		"platform_editor_blocks_patch_3": {
 			"type": "boolean"
 		},