@atlaskit/editor-synced-block-provider 4.3.2 → 4.3.3

package/AGENTS.md

@@ -1,9 +1,9 @@
 # Synced Block Provider — Developer Agent Guide
 
-> **Package**: `@atlaskit/editor-synced-block-provider` **Purpose**: Data layer for synced blocks —
-> store managers, block service API client, ARI generation, permissions, media tokens. **Full
-> Knowledge Base**:
-> [Synced Blocks — Comprehensive Knowledge Base](https://hello.atlassian.net/wiki/spaces/egcuc/pages/6679548384)
+> **Package**: `@atlaskit/editor-synced-block-provider`
+>
+> **For workflow guidance, debugging, and cross-package task guides, load the `synced-blocks` skill:**
+> `get_skill(skill_name_or_path="platform/packages/editor/.rovodev/skills/synced-blocks/SKILL.md")`
 
 ---
 
@@ -19,29 +19,29 @@ plugin and the renderer across Confluence and Jira.
 
 ```
 src/
-├── index.ts                          ← Barrel export
+├── index.ts                          # Barrel export
 ├── store-manager/
-│   ├── syncBlockStoreManager.ts      ← Parent coordinator for source + reference managers
-│   ├── referenceSyncBlockStoreManager.ts ← Reference block lifecycle, cache, subscriptions, flush
-│   └── sourceSyncBlockStoreManager.ts    ← Source block create, update, delete, flush
+│   ├── syncBlockStoreManager.ts      # Parent coordinator for source + reference managers
+│   ├── referenceSyncBlockStoreManager.ts # Reference block lifecycle, cache, subscriptions, flush
+│   └── sourceSyncBlockStoreManager.ts    # Source block create, update, delete, flush
 ├── clients/
 │   ├── block-service/
-│   │   ├── blockService.ts           ← Block service API client (fetch, batch, CRUD)
-│   │   └── ari.ts                    ← Block ARI generation/parsing
+│   │   ├── blockService.ts           # Block service API client (fetch, batch, CRUD)
+│   │   └── ari.ts                    # Block ARI generation/parsing
 │   ├── confluence/
-│   │   ├── ari.ts                    ← Confluence page ARI generation/parsing
-│   │   └── fetchMediaToken.ts        ← Media token fetching via GraphQL (MediaUploadTokenQuery)
+│   │   ├── ari.ts                    # Confluence page ARI generation/parsing
+│   │   └── fetchMediaToken.ts        # Media token fetching via GraphQL (MediaUploadTokenQuery)
 │   └── jira/
-│       └── ari.ts                    ← Jira work item ARI generation/parsing
+│       └── ari.ts                    # Jira work item ARI generation/parsing
 ├── providers/
 │   └── block-service/
-│       └── blockServiceAPI.ts        ← Provider factory and API helpers
-└── types/                            ← Shared types
+│       └── blockServiceAPI.ts        # Provider factory and API helpers
+└── types/                            # Shared types
 ```
 
 ---
 
-## Key Concepts
+## Key Exports and Types
 
 ### Store Manager Hierarchy
 
@@ -49,81 +49,41 @@ src/
 SyncBlockStoreManager (parent coordinator)
 ├── SourceSyncBlockStoreManager
 │   ├── create(content) → Block Service API → returns resourceId
-│   ├── update(resourceId, content) → debounced 3s write
-│   ├── delete(resourceId) → soft delete
-│   └── flush() → persist all pending changes on page save
+│   ├── updateSyncBlockData(node) → marks isDirty, caches content
+│   ├── flush() → persist all dirty changes to backend
+│   ├── hasUnsavedChanges() → checks isDirty + hasReceivedContentChange
+│   └── delete(resourceId) → soft delete with confirmation
 └── ReferenceSyncBlockStoreManager
     ├── fetchSyncBlocksData(nodes) → batch fetch with deduplication
-    ├── subscribeToSyncBlock(resourceId, localId, callback) → AGG WebSocket
+    ├── subscribeToSyncBlock(resourceId, callback) → AGG WebSocket
     ├── fetchSyncBlockSourceInfo(resourceId) → title, URL metadata
-    ├── getFromCache(resourceId) → retrieve cached data
-    ├── flush() → save reference changes to backend
     └── destroy() → cleanup subscriptions and batchers
 ```
 
-### ARI Formats & Utilities
+### ARI Utilities
 
-| Function                                                     | ARI Pattern               | Example                                                         |
-| ------------------------------------------------------------ | ------------------------- | --------------------------------------------------------------- |
-| `generateBlockAri({cloudId, parentId, product, resourceId})` | Source block ARI          | `ari:cloud:block::{cloudId}/confluence-page:{pageId}/{localId}` |
-| `generateBlockAriFromReference({cloudId, resourceId})`       | Reference block ARI       | —                                                               |
-| `getConfluencePageAri({pageId, cloudId, pageType})`          | Confluence page           | `ari:cloud:confluence::{cloudId}:page/{pageId}`                 |
-| `getJiraWorkItemAri({cloudId, workItemId})`                  | Jira issue                | `ari:cloud:jira::{cloudId}:work-item/{issueId}`                 |
-| `getJiraWorkItemIdFromAri(ari)`                              | Extract issue ID from ARI | —                                                               |
+| Function                                                     | Purpose                    |
+| ------------------------------------------------------------ | -------------------------- |
+| `generateBlockAri({cloudId, parentId, product, resourceId})` | Generate source block ARI  |
+| `generateBlockAriFromReference({cloudId, resourceId})`       | Generate reference ARI     |
+| `getConfluencePageAri({pageId, cloudId, pageType})`          | Confluence page ARI        |
+| `getJiraWorkItemAri({cloudId, workItemId})`                  | Jira issue ARI             |
 
 ### Block Service API
 
 The client in `clients/block-service/blockService.ts` communicates via GraphQL at
-`/gateway/api/graphql`:
-
-- **Fetch**: Single or batch block content retrieval
-- **Create**: Register new source block with content
-- **Update**: Push content changes (debounced 3s)
-- **Delete**: Soft delete a source block
-- **Source Info**: Fetch metadata (source page title, URL)
-- **References Info**: Fetch list of locations referencing a block
+`/gateway/api/graphql`: Fetch, Create, Update (debounced 3s), Delete, Source Info, References Info.
 
 ### Media Token Fetching
 
 `fetchMediaToken(contentId)` → GraphQL `MediaUploadTokenQuery` → returns
 `{token, config: {clientId, fileStoreUrl}, collectionId}`
 
-Used when synced blocks contain media (images, files) — the reference needs a valid token to render
-media from the source page.
-
----
-
-## Common Tasks
-
-### Adding a new API method
-
-1. Add the GraphQL query/mutation in `clients/block-service/blockService.ts`
-2. Expose it through the appropriate store manager
-3. Export from `src/index.ts` if needed by product integrations
-4. Add tests in `editor-synced-block-provider-tests`
-
-### Debugging data issues
-
-1. Check `ReferenceSyncBlockStoreManager` cache state
-2. Verify ARI format matches expected pattern for the product
-3. Check Block Service API responses in network tab (look for `/gateway/api/graphql`)
-4. Use analytics:
-   [HOW-TO: Debug errors](https://hello.atlassian.net/wiki/spaces/egcuc/pages/6342760320)
-
-### Adding support for a new product
-
-1. Create ARI utilities in `clients/{product}/ari.ts`
-2. Ensure `generateBlockAri` supports the new product type
-3. Add media token fetching if the product has media content
-4. Update store managers if the product has unique lifecycle requirements
-
 ---
 
 ## Related Packages
 
-- **Plugin**: `platform/packages/editor/editor-plugin-synced-block/` — uses store managers
-- **Renderer**: `platform/packages/editor/editor-synced-block-renderer/` — uses fetch provider
-- **Confluence**: `confluence/next/packages/fabric-providers/src/SyncedBlockProvider.ts` — wraps
-  this provider
-- **Jira**: `jira/src/packages/issue/issue-view-synced-block-provider/` — wraps this provider with
-  Relay
+- **Plugin**: `platform/packages/editor/editor-plugin-synced-block/`
+- **Renderer**: `platform/packages/editor/editor-synced-block-renderer/`
+- **Confluence**: `confluence/next/packages/fabric-providers/src/SyncedBlockProvider.ts`
+- **Jira**: `jira/src/packages/issue/issue-view-synced-block-provider/`

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @atlaskit/editor-synced-block-provider
 
+## 4.3.3
+
+### Patch Changes
+
+- [`15deee785151b`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/15deee785151b) -
+  EDITOR-6174 Pass node to createBodiedSyncBlockNode to cache content on creation, preventing false
+  unsaved changes on page refresh
+- Updated dependencies
+
 ## 4.3.2
 
 ### Patch Changes

package/dist/cjs/store-manager/sourceSyncBlockStoreManager.js

@@ -339,10 +339,12 @@ var SourceSyncBlockStoreManager = exports.SourceSyncBlockStoreManager = /*#__PUR
     /**
      * Create a bodiedSyncBlock node with empty content to backend
      * @param attrs attributes Ids of the node
+     * @param node the ProseMirror node to cache
+     * @param onCompletion callback invoked when creation completes
      */
   }, {
     key: "createBodiedSyncBlockNode",
-    value: function createBodiedSyncBlockNode(attrs, onCompletion) {
+    value: function createBodiedSyncBlockNode(attrs, node, onCompletion) {
       var _this4 = this;
       if (this.viewMode === 'view' && (0, _platformFeatureFlags.fg)('platform_synced_block_patch_8')) {
         return;
@@ -354,6 +356,10 @@ var SourceSyncBlockStoreManager = exports.SourceSyncBlockStoreManager = /*#__PUR
         if (!this.dataProvider) {
           throw new Error('Data provider not set');
         }
+        if ((0, _platformFeatureFlags.fg)('platform_synced_block_update_refactor')) {
+          // add the node to the cache
+          this.updateSyncBlockData(node);
+        }
         this.creationCompletionCallbacks.set(resourceId, onCompletion);
         (_this$createExperienc = this.createExperience) === null || _this$createExperienc === void 0 || _this$createExperienc.start({});
         this.dataProvider.createNodeData({

package/dist/es2019/store-manager/sourceSyncBlockStoreManager.js

@@ -269,8 +269,10 @@ export class SourceSyncBlockStoreManager {
   /**
    * Create a bodiedSyncBlock node with empty content to backend
    * @param attrs attributes Ids of the node
+   * @param node the ProseMirror node to cache
+   * @param onCompletion callback invoked when creation completes
    */
-  createBodiedSyncBlockNode(attrs, onCompletion) {
+  createBodiedSyncBlockNode(attrs, node, onCompletion) {
     if (this.viewMode === 'view' && fg('platform_synced_block_patch_8')) {
       return;
     }
@@ -283,6 +285,10 @@ export class SourceSyncBlockStoreManager {
       if (!this.dataProvider) {
         throw new Error('Data provider not set');
       }
+      if (fg('platform_synced_block_update_refactor')) {
+        // add the node to the cache
+        this.updateSyncBlockData(node);
+      }
       this.creationCompletionCallbacks.set(resourceId, onCompletion);
       (_this$createExperienc = this.createExperience) === null || _this$createExperienc === void 0 ? void 0 : _this$createExperienc.start({});
       this.dataProvider.createNodeData({

package/dist/esm/store-manager/sourceSyncBlockStoreManager.js

@@ -332,10 +332,12 @@ export var SourceSyncBlockStoreManager = /*#__PURE__*/function () {
     /**
      * Create a bodiedSyncBlock node with empty content to backend
      * @param attrs attributes Ids of the node
+     * @param node the ProseMirror node to cache
+     * @param onCompletion callback invoked when creation completes
      */
   }, {
     key: "createBodiedSyncBlockNode",
-    value: function createBodiedSyncBlockNode(attrs, onCompletion) {
+    value: function createBodiedSyncBlockNode(attrs, node, onCompletion) {
       var _this4 = this;
       if (this.viewMode === 'view' && fg('platform_synced_block_patch_8')) {
         return;
@@ -347,6 +349,10 @@ export var SourceSyncBlockStoreManager = /*#__PURE__*/function () {
         if (!this.dataProvider) {
           throw new Error('Data provider not set');
         }
+        if (fg('platform_synced_block_update_refactor')) {
+          // add the node to the cache
+          this.updateSyncBlockData(node);
+        }
         this.creationCompletionCallbacks.set(resourceId, onCompletion);
         (_this$createExperienc = this.createExperience) === null || _this$createExperienc === void 0 || _this$createExperienc.start({});
         this.dataProvider.createNodeData({

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

@@ -57,8 +57,10 @@ export declare class SourceSyncBlockStoreManager {
     /**
      * Create a bodiedSyncBlock node with empty content to backend
      * @param attrs attributes Ids of the node
+     * @param node the ProseMirror node to cache
+     * @param onCompletion callback invoked when creation completes
      */
-    createBodiedSyncBlockNode(attrs: SyncBlockAttrs, onCompletion: OnCompletion): void;
+    createBodiedSyncBlockNode(attrs: SyncBlockAttrs, node: PMNode, onCompletion: OnCompletion): void;
     private setPendingDeletion;
     private delete;
     isRetryingDeletion(): boolean;

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

@@ -57,8 +57,10 @@ export declare class SourceSyncBlockStoreManager {
     /**
      * Create a bodiedSyncBlock node with empty content to backend
      * @param attrs attributes Ids of the node
+     * @param node the ProseMirror node to cache
+     * @param onCompletion callback invoked when creation completes
      */
-    createBodiedSyncBlockNode(attrs: SyncBlockAttrs, onCompletion: OnCompletion): void;
+    createBodiedSyncBlockNode(attrs: SyncBlockAttrs, node: PMNode, onCompletion: OnCompletion): void;
     private setPendingDeletion;
     private delete;
     isRetryingDeletion(): boolean;

package/package.json

@@ -29,7 +29,7 @@
 		"@atlaskit/editor-prosemirror": "^7.3.0",
 		"@atlaskit/node-data-provider": "^9.0.0",
 		"@atlaskit/platform-feature-flags": "^1.1.0",
-		"@atlaskit/tmp-editor-statsig": "^54.1.0",
+		"@atlaskit/tmp-editor-statsig": "^54.4.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^0.20.0",
 		"graphql-ws": "^5.14.2",
@@ -38,7 +38,7 @@
 		"uuid": "^3.1.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^112.16.0",
+		"@atlaskit/editor-common": "^112.18.0",
 		"react": "^18.2.0"
 	},
 	"devDependencies": {
@@ -81,7 +81,7 @@
 		}
 	},
 	"name": "@atlaskit/editor-synced-block-provider",
-	"version": "4.3.2",
+	"version": "4.3.3",
 	"description": "Synced Block Provider for @atlaskit/editor-plugin-synced-block",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",