@atlaskit/editor-plugin-local-id 6.0.21 → 6.0.22

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @atlaskit/editor-plugin-local-id
 
+## 6.0.22
+
+### Patch Changes
+
+- [`14803a836f641`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/14803a836f641) -
+  Update README.md and 0-intro.tsx
+- Updated dependencies
+
 ## 6.0.21
 
 ### Patch Changes

package/README.md

@@ -1,43 +1,57 @@
-# Editor Plugin: `editor-plugin-local-id`
+# Editor Plugin Local ID
 
-## 🧠 Overview
+LocalId plugin for @atlaskit/editor-core
 
-This plugin ensures that all non-ignored nodes in the document have unique `localId` attributes. It combines **two approaches** for optimal performance:
+**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 Local ID plugin ensures that all non-ignored nodes in the document have unique `localId` attributes. It combines two approaches for optimal performance:
 
 1. **One-time initialization scan** - Adds missing local IDs to existing nodes when the editor starts
 2. **Incremental transaction processing** - Adds local IDs to new nodes as they're created
 
----
+## Key features
+
+- **Automatic local ID assignment** - Ensures all nodes without local IDs receive unique identifiers
+- **Efficient initialization** - Uses `requestIdleCallback` with `requestAnimationFrame` fallback for Safari
+- **Incremental updates** - Processes only changed nodes during transactions
+- **Node filtering** - Skips ignored node types (text, hardBreak, mediaGroup)
+- **Batch processing** - Applies all updates in a single transaction
+- **Error tracking** - Optional error reporting for local ID changes via watchmen plugin
+- **Plugin actions** - Provides `getNode` and `replaceNode` actions for querying and modifying nodes by local ID
 
-## ⚙️ How It Works
+### How It Works
+
+#### Initialization Phase
 
-### Initialization Phase
 - **Trigger**: Uses the editor view's initialization lifecycle to schedule the scan
 - **Execution**: Performs a single document traversal during browser idle time
 - **Scheduling**: Uses `requestIdleCallback` with `requestAnimationFrame` fallback for Safari
 - **Purpose**: Ensures all existing nodes have local IDs
 
-### Transaction Processing Phase
+#### Transaction Processing Phase
+
 - **Trigger**: Activates on every document-changing transaction
 - **Execution**: Processes only the new/changed nodes from transaction steps
 - **Performance**: Only scans changed ranges, not the entire document
 - **Purpose**: Adds local IDs to newly created nodes
 
-### Node Processing
+#### Node Processing
+
 For each node (both during initialization and transaction processing):
 - **Ignored nodes**: Always skipped (text, hardBreak)
 - **Nodes with existing localId**: Left unchanged
 - **Nodes without localId**: New UUID generated and assigned
 
-### Transaction Handling
+#### Transaction Handling
+
 - **Incremental updates**: Only processes nodes that actually changed
 - **Efficient scanning**: Uses `step.getMap()` to identify changed ranges
 - **Position accuracy**: Gets precise document positions for all changed nodes
 - **Batch processing**: All updates applied in a single transaction
 
----
-
-## ✅ Behavior
+#### Behavior
 
 | Case | Action Taken | Transaction Impact |
 |------|-------------|-------------------|
@@ -48,5 +62,27 @@ For each node (both during initialization and transaction processing):
 | Cut operations | Skipped to avoid conflicts | No transaction |
 | Document unchanged | Early exit | No transaction |
 
----
+## Install
+
+- **Install** - *yarn add @atlaskit/editor-plugin-local-id*
+- **npm** - [@atlaskit/editor-plugin-local-id](https://www.npmjs.com/package/@atlaskit/editor-plugin-local-id)
+- **Source** - [Bitbucket](https://bitbucket.org/atlassian/atlassian-frontend/src/master/packages/editor/editor-plugin-local-id)
+- **Bundle** - [unpkg.com](https://unpkg.com/@atlaskit/editor-plugin-local-id/dist/)
+
+## Usage
+
+**Internal use only**
+
+@atlaskit/editor-plugin-local-id 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 local-id](https://atlaskit.atlassian.com/packages/editor/editor-plugin-local-id) 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,61 @@ The \`dependencies\`, \`configuration\`, \`state\`, \`actions\`, and \`commands\
 below:
 
 ${code`
-type LocalIdPlugin = NextEditorPlugin<'localId'>
+export type ActionProps = {
+	localId: string;
+};
+
+export type LocalIdStatusCode =
+	| 'current'
+	| 'localChangeByAttr'
+	| 'localChangeBySetAttrs'
+	| 'localChangeByBatchAttrs'
+	| 'localChangeByReplace'
+	| 'localChangeByDelete'
+	| 'localChangeByReplaceAround'
+	| 'localChangeByUnknown'
+	| 'remoteChangeByAttr'
+	| 'remoteChangeBySetAttrs'
+	| 'remoteChangeByBatchAttrs'
+	| 'remoteChangeByReplace'
+	| 'remoteChangeByDelete'
+	| 'remoteChangeByReplaceAround'
+	| 'remoteChangeByUnknown'
+	| 'AIChangeByAttr'
+	| 'AIChangeBySetAttrs'
+	| 'AIChangeByBatchAttrs'
+	| 'AIChangeByReplace'
+	| 'AIChangeByDelete'
+	| 'AIChangeByReplaceAround'
+	| 'AIChangeByUnknown'
+	| 'docChangeByAttr'
+	| 'docChangeBySetAttrs'
+	| 'docChangeByBatchAttrs'
+	| 'docChangeByReplace'
+	| 'docChangeByDelete'
+	| 'docChangeByReplaceAround'
+	| 'docChangeByUnknown';
+
+export interface LocalIdSharedState {
+	localIdStatus: Map<string, LocalIdStatusCode> | undefined;
+	localIdWatchmenEnabled: boolean | undefined;
+}
+
+export type LocalIdPlugin = NextEditorPlugin<
+	'localId',
+	{
+		actions: {
+			getNode: (props: ActionProps) => NodeWithPos | undefined;
+			replaceNode: (props: ActionProps & { value: Node }) => boolean;
+		};
+		dependencies: [
+			CompositionPlugin,
+			OptionalPlugin<CollabEditPlugin>,
+			OptionalPlugin<LimitedModePlugin>,
+		];
+		sharedState: LocalIdSharedState | undefined;
+	}
+>;
 `}
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-local-id",
-	"version": "6.0.21",
+	"version": "6.0.22",
 	"description": "LocalId plugin for @atlaskit/editor-core",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -34,7 +34,7 @@
 		"@atlaskit/editor-plugin-limited-mode": "^5.0.0",
 		"@atlaskit/editor-prosemirror": "^7.3.0",
 		"@atlaskit/platform-feature-flags": "^1.1.0",
-		"@atlaskit/tmp-editor-statsig": "^55.0.0",
+		"@atlaskit/tmp-editor-statsig": "^55.1.0",
 		"@babel/runtime": "^7.0.0",
 		"raf-schd": "^4.0.3"
 	},