@atlaskit/editor-plugin-synced-block 6.1.7 → 6.1.8

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @atlaskit/editor-plugin-synced-block
 
+## 6.1.8
+
+### Patch Changes
+
+- [`fa146e17e08d6`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/fa146e17e08d6) -
+  Update README.md and 0-intro.tsx
+- Updated dependencies
+
 ## 6.1.7
 
 ### Patch Changes

package/README.md

@@ -1 +1,47 @@
-# Editor plugin synced block
+# Editor Plugin Synced Block
+
+Synced Block plugin for @atlaskit/editor-core
+
+**Note:** This component is designed for internal Atlassian development.
+External contributors will be able to use this component but will not be able to submit issues.
+
+## Overview
+
+The Synced Block plugin enables content synchronization across multiple locations within the Atlassian Editor. It provides functionality for creating, managing, and rendering synced block nodes that automatically update across all references. This plugin supports both simple reference blocks and bodied synced blocks with full editing capabilities.
+
+## Key features
+
+- **Synced block creation and management** - Create and manage synced blocks with automatic reference tracking
+- **Bodied sync blocks** - Support for editable synced blocks with full content capabilities
+- **Reference synchronization** - Automatically synchronize content changes across all block references
+- **Floating toolbar integration** - Contextual toolbar for synced block operations (delete, unsync, view locations)
+- **Quick insert support** - Easy insertion of synced blocks through quick insert menu
+- **Block menu integration** - Block menu support for creating and managing synced blocks
+- **Offline handling** - Graceful handling of offline scenarios with appropriate user notifications
+- **Analytics integration** - Built-in analytics event tracking for synced block operations
+- **Copy to clipboard** - Copy synced block references for sharing across documents
+
+## Install
+---
+- **Install** - *yarn add @atlaskit/editor-plugin-synced-block*
+- **npm** - [@atlaskit/editor-plugin-synced-block](https://www.npmjs.com/package/@atlaskit/editor-plugin-synced-block)
+- **Source** - [Bitbucket](https://bitbucket.org/atlassian/atlassian-frontend/src/master/packages/editor/editor-plugin-synced-block)
+- **Bundle** - [unpkg.com](https://unpkg.com/@atlaskit/editor-plugin-synced-block/dist/)
+
+## Usage
+---
+**Internal use only**
+
+@atlaskit/editor-plugin-synced-block is intended for internal use by the @atlaskit/editor-core and as a plugin dependency of the Editor within your product.
+
+Direct use of this component is not supported.
+
+Please see [Atlaskit - Editor plugin synced block](https://atlaskit.atlassian.com/packages/editor/editor-plugin-synced-block) for documentation and examples for this package.
+
+## Support
+---
+For internal Atlassian, visit the slack channel [#help-editor](https://atlassian.slack.com/archives/CFG3PSQ9E) for support or visit [go/editor-help](https://go/editor-help) to submit a bug.
+
+## License
+---
+Please see [Atlassian Frontend - License](https://hello.atlassian.net/wiki/spaces/AF/pages/2589099144/Documentation#License) for more licensing information.

package/docs/0-intro.tsx

@@ -31,7 +31,97 @@ The \`dependencies\`, \`configuration\`, \`state\`, \`actions\`, and \`commands\
 below:
 
 ${code`
-type SyncedBlockPlugin = NextEditorPlugin<'syncedBlock'>
+export type SyncedBlockEditorProps = {
+  defaultDocument: JSONDocNode;
+  onChange: (
+    editorView: EditorView,
+    meta: {
+      /**
+       * Indicates whether or not the change may be unnecessary to listen to (dirty
+       * changes can generally be ignored).
+       *
+       * This might be changes to media attributes for example when it gets updated
+       * due to initial setup.
+       *
+       * We still fire these events however to avoid a breaking change.
+       */
+      isDirtyChange: boolean;
+      source: 'local' | 'remote';
+    },
+  ) => void;
+  onEditorReady: ({
+    editorView,
+    eventDispatcher,
+  }: {
+    editorView: EditorView;
+    eventDispatcher: EventDispatcher;
+  }) => void;
+  popupsBoundariesElement: HTMLElement;
+  popupsMountPoint: HTMLElement;
+};
+
+export type SyncedBlockRendererProps = {
+  api?: ExtractInjectionAPI<SyncedBlockPlugin>;
+  syncBlockFetchResult: UseFetchSyncBlockDataResult;
+};
+
+export interface SyncedBlockPluginOptions extends LongPressSelectionPluginOptions {
+	/**
+	 * Enables Live Page specific behaviour for the synced block plugin.
+	 *
+	 * It is only supported for use by Confluence.
+	 *
+	 * @default false
+	 */
+	__livePage?: boolean;
+  enableSourceCreation?: boolean;
+  syncBlockDataProvider: SyncBlockDataProviderInterface;
+  syncedBlockRenderer: (props: SyncedBlockRendererProps) => React.JSX.Element;
+}
+
+export type SyncedBlockPlugin = NextEditorPlugin<
+  'syncedBlock',
+  {
+    actions: {
+      /**
+       * Save content of bodiedSyncBlock nodes in local cache to backend.
+       * This action allows bodiedSyncBlock to be saved in sync with product saving experience
+       * as per {@link https://hello.atlassian.net/wiki/spaces/egcuc/pages/5932393240/Synced+Blocks+Save+refresh+principles}
+       *
+       * @returns true if saving all nodes successfully, false if fail to save some/all nodes
+       */
+      flushBodiedSyncBlocks: () => Promise<boolean>;
+      /**
+       * Save reference synced blocks on the document (tracked by local cache)to the backend.
+       * This action allows syncBlock on the document to be saved in sync with product saving experience
+       * as per {@link https://hello.atlassian.net/wiki/spaces/egcuc/pages/5932393240/Synced+Blocks+Save+refresh+principles}
+       *
+       * @returns true if flushing all syncBlocks successfully, false otherwise
+       */
+      flushSyncedBlocks: () => Promise<boolean>;
+    };
+    commands: {
+      copySyncedBlockReferenceToClipboard: (inputMethod: INPUT_METHOD) => EditorCommand;
+      insertSyncedBlock: () => EditorCommand;
+    };
+    dependencies: [
+      SelectionPlugin,
+      FloatingToolbarPlugin,
+      DecorationsPlugin,
+      OptionalPlugin<BlockControlsPlugin>,
+      OptionalPlugin<ToolbarPlugin>,
+      OptionalPlugin<BlockMenuPlugin>,
+      OptionalPlugin<AnalyticsPlugin>,
+      OptionalPlugin<ConnectivityPlugin>,
+      OptionalPlugin<EditorViewModePlugin>,
+      OptionalPlugin<ContentFormatPlugin>,
+      OptionalPlugin<UserIntentPlugin>,
+      OptionalPlugin<FocusPlugin>,
+    ];
+    pluginConfiguration: SyncedBlockPluginOptions | undefined;
+    sharedState: SyncedBlockSharedState | undefined;
+  }
+>;
 `}
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-synced-block",
-	"version": "6.1.7",
+	"version": "6.1.8",
 	"description": "SyncedBlock plugin for @atlaskit/editor-core",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",