npm.io
31.0.0 • Published 2d ago

@atlaskit/editor-plugin-local-id

Licence
Apache-2.0
Version
31.0.0
Deps
8
Size
160 kB
Vulns
0
Weekly
0

Editor Plugin Local ID

LocalId 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 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
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
  • 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

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
  • 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
Case Action Taken Transaction Impact
Existing node without localId (initialization) localId is added Single transaction with all changes
New node added without localId (transaction) localId is added Single transaction with all changes
Node already has a localId Left unchanged No transaction
Only selection changes No action taken No transaction
Cut operations Skipped to avoid conflicts No transaction
Document unchanged Early exit No transaction

Install

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 for documentation and examples for this package.

Support

For internal Atlassian, visit the slack channel #help-editor for support or visit go/editor-help to submit a bug.

License

Please see Atlassian Frontend - License for more licensing information.