@atlaskit/editor-synced-block-provider 4.3.1 → 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,26 @@
 # @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
+
+- [`eaeabd907b737`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/eaeabd907b737) -
+  Move unregistered references logic into a separate method.
+- [`38e89dd6515da`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/38e89dd6515da) -
+  Disable synced block write operations (create, update, delete, flush) when the editor is in view
+  mode, gated behind platform_synced_block_patch_8. This prevents unintended block service mutations
+  (e.g. deletion modals, data loss) when the editor is used in read-only contexts such as Version
+  History.
+
 ## 4.3.1
 
 ### Patch Changes

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

@@ -13,6 +13,7 @@ var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/creat
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _isEqual = _interopRequireDefault(require("lodash/isEqual"));
 var _monitoring = require("@atlaskit/editor-common/monitoring");
+var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 var _types = require("../common/types");
 var _errorHandling = require("../utils/errorHandling");
 var _experienceTracking = require("../utils/experienceTracking");
@@ -37,7 +38,7 @@ var CACHE_KEY_PREFIX = 'sync-block-data-';
 var ReferenceSyncBlockStoreManager = exports.ReferenceSyncBlockStoreManager = /*#__PURE__*/function () {
   // Track the setTimeout handle for queued flush so we can cancel it on destroy
 
-  function ReferenceSyncBlockStoreManager(dataProvider) {
+  function ReferenceSyncBlockStoreManager(dataProvider, viewMode) {
     var _this = this,
       _this$dataProvider;
     (0, _classCallCheck2.default)(this, ReferenceSyncBlockStoreManager);
@@ -52,6 +53,7 @@ var ReferenceSyncBlockStoreManager = exports.ReferenceSyncBlockStoreManager = /*
     // Track if another flush is needed after the current one completes
     (0, _defineProperty2.default)(this, "flushNeededAfterCurrent", false);
     this.dataProvider = dataProvider;
+    this.viewMode = viewMode;
     this.syncBlockFetchDataRequests = new Map();
     this.syncBlockSourceInfoRequests = new Map();
     this.newlyAddedSyncBlocks = new Set();
@@ -702,14 +704,20 @@ var ReferenceSyncBlockStoreManager = exports.ReferenceSyncBlockStoreManager = /*
         return _regenerator.default.wrap(function _callee3$(_context4) {
           while (1) switch (_context4.prev = _context4.next) {
             case 0:
-              if (this.isCacheDirty) {
+              if (!(this.viewMode === 'view' && (0, _platformFeatureFlags.fg)('platform_synced_block_patch_8'))) {
                 _context4.next = 2;
                 break;
               }
-              return _context4.abrupt("return", true);
+              return _context4.abrupt("return", false);
             case 2:
+              if (this.isCacheDirty) {
+                _context4.next = 4;
+                break;
+              }
+              return _context4.abrupt("return", true);
+            case 4:
               if (!this.isFlushInProgress) {
-                _context4.next = 7;
+                _context4.next = 9;
                 break;
               }
               // Mark that another flush is needed after the current one completes
@@ -717,22 +725,22 @@ var ReferenceSyncBlockStoreManager = exports.ReferenceSyncBlockStoreManager = /*
 
               // We return true here because we know the pending flush will handle the dirty cache
               return _context4.abrupt("return", true);
-            case 7:
+            case 9:
               this.isFlushInProgress = true;
-            case 8:
+            case 10:
               success = true; // a copy of the subscriptions STRUCTURE (without the callbacks)
               // To be saved as the last flushed structure if the flush is successful
               syncedBlocksToFlush = {};
-              _context4.prev = 10;
+              _context4.prev = 12;
               if (this.dataProvider) {
-                _context4.next = 13;
+                _context4.next = 15;
                 break;
               }
               throw new Error('Data provider not set');
-            case 13:
+            case 15:
               blocks = []; // First, build the complete subscription structure
               _iterator = _createForOfIteratorHelper(this._subscriptionManager.getSubscriptions().entries());
-              _context4.prev = 15;
+              _context4.prev = 17;
               _loop = /*#__PURE__*/_regenerator.default.mark(function _loop() {
                 var _step$value, resourceId, callbacks;
                 return _regenerator.default.wrap(function _loop$(_context3) {
@@ -754,34 +762,34 @@ var ReferenceSyncBlockStoreManager = exports.ReferenceSyncBlockStoreManager = /*
                 }, _loop);
               });
               _iterator.s();
-            case 18:
+            case 20:
               if ((_step = _iterator.n()).done) {
-                _context4.next = 22;
+                _context4.next = 24;
                 break;
               }
-              return _context4.delegateYield(_loop(), "t0", 20);
-            case 20:
-              _context4.next = 18;
-              break;
+              return _context4.delegateYield(_loop(), "t0", 22);
             case 22:
-              _context4.next = 27;
+              _context4.next = 20;
               break;
             case 24:
-              _context4.prev = 24;
-              _context4.t1 = _context4["catch"](15);
+              _context4.next = 29;
+              break;
+            case 26:
+              _context4.prev = 26;
+              _context4.t1 = _context4["catch"](17);
               _iterator.e(_context4.t1);
-            case 27:
-              _context4.prev = 27;
+            case 29:
+              _context4.prev = 29;
               _iterator.f();
-              return _context4.finish(27);
-            case 30:
+              return _context4.finish(29);
+            case 32:
               if (!(0, _isEqual.default)(syncedBlocksToFlush, this.lastFlushedSyncedBlocks)) {
-                _context4.next = 33;
+                _context4.next = 35;
                 break;
               }
               this.isCacheDirty = false; // Reset since we're considering this a successful no-op flush
               return _context4.abrupt("return", true);
-            case 33:
+            case 35:
               // reset isCacheDirty early to prevent race condition
               // There is a race condition where if a user makes changes (create/delete) to a reference sync block
               // on a live page and the reference sync block is being saved while the user
@@ -789,9 +797,9 @@ var ReferenceSyncBlockStoreManager = exports.ReferenceSyncBlockStoreManager = /*
               // exactly at a time when the updateReferenceData is being executed asynchronously.
               this.isCacheDirty = false;
               (_this$saveExperience = this.saveExperience) === null || _this$saveExperience === void 0 || _this$saveExperience.start();
-              _context4.next = 37;
+              _context4.next = 39;
               return this.dataProvider.updateReferenceData(blocks);
-            case 37:
+            case 39:
               updateResult = _context4.sent;
               if (!updateResult.success) {
                 success = false;
@@ -800,11 +808,11 @@ var ReferenceSyncBlockStoreManager = exports.ReferenceSyncBlockStoreManager = /*
                 });
                 (_this$fireAnalyticsEv6 = this.fireAnalyticsEvent) === null || _this$fireAnalyticsEv6 === void 0 || _this$fireAnalyticsEv6.call(this, (0, _errorHandling.updateReferenceErrorPayload)(updateResult.error || 'Failed to update reference synced blocks on the document'));
               }
-              _context4.next = 47;
+              _context4.next = 49;
               break;
-            case 41:
-              _context4.prev = 41;
-              _context4.t2 = _context4["catch"](10);
+            case 43:
+              _context4.prev = 43;
+              _context4.t2 = _context4["catch"](12);
               success = false;
               (0, _monitoring.logException)(_context4.t2, {
                 location: 'editor-synced-block-provider/referenceSyncBlockStoreManager'
@@ -813,8 +821,8 @@ var ReferenceSyncBlockStoreManager = exports.ReferenceSyncBlockStoreManager = /*
                 reason: _context4.t2.message
               });
               (_this$fireAnalyticsEv7 = this.fireAnalyticsEvent) === null || _this$fireAnalyticsEv7 === void 0 || _this$fireAnalyticsEv7.call(this, (0, _errorHandling.updateReferenceErrorPayload)(_context4.t2.message));
-            case 47:
-              _context4.prev = 47;
+            case 49:
+              _context4.prev = 49;
               if (!success) {
                 // set isCacheDirty back to true for cases where it failed to update the reference synced blocks on the BE
                 this.isCacheDirty = true;
@@ -836,14 +844,14 @@ var ReferenceSyncBlockStoreManager = exports.ReferenceSyncBlockStoreManager = /*
                   void _this7.flush();
                 }, 0);
               }
-              return _context4.finish(47);
-            case 52:
+              return _context4.finish(49);
+            case 54:
               return _context4.abrupt("return", success);
-            case 53:
+            case 55:
             case "end":
               return _context4.stop();
           }
-        }, _callee3, this, [[10, 41, 47, 52], [15, 24, 27, 30]]);
+        }, _callee3, this, [[12, 43, 49, 54], [17, 26, 29, 32]]);
       }));
       function flush() {
         return _flush.apply(this, arguments);