Skip to main content
Reference status

This page predates the current package split. Use the current package guides for checked installation, public imports, and onboarding examples. The detailed examples below have not all been revalidated.

@barocss/dom-observer

DOM mutation observer with text change detection and collaborative editing support.

Purpose​

Observes DOM changes and detects meaningful mutations:

  • Structure changes (node addition/removal)
  • Text content changes
  • Attribute changes
  • Filters changes using data-bc-* attributes

Key Exports​

  • MutationObserverManager - DOM mutation observer manager

Basic Usage​

import { MutationObserverManager } from '@barocss/dom-observer';

const observer = new MutationObserverManager({
  target: contentEditableElement,
  onStructureChange: (event) => {
    console.log('Structure changed:', event);
  },
  onTextChange: (event) => {
    console.log('Text changed:', event);
  },
  onNodeUpdate: (event) => {
    console.log('Node updated:', event);
  }
});

// Start observing
observer.start();

// Stop observing
observer.stop();

Change Detection​

Structure Changes​

Detects node addition, removal, and movement:

observer.onStructureChange = (event) => {
  if (event.type === 'add') {
    // Node added
  } else if (event.type === 'remove') {
    // Node removed
  } else if (event.type === 'move') {
    // Node moved
  }
};

Text Changes​

Detects text content modifications:

observer.onTextChange = (event) => {
  console.log('Old text:', event.oldText);
  console.log('New text:', event.newText);
  console.log('Position:', event.startOffset, event.endOffset);
};

Attribute Changes​

Detects attribute modifications:

observer.onNodeUpdate = (event) => {
  console.log('Attribute:', event.attributeName);
  console.log('Old value:', event.oldValue);
  console.log('New value:', event.newValue);
};

Data Attribute Filtering​

Filter changes using data-bc-* attributes:

const observer = new MutationObserverManager({
  target: element,
  filterByDataAttributes: true  // Only track nodes with data-bc-* attributes
});

This ensures only meaningful changes are tracked, ignoring decorators and other non-content elements.

Integration​

DOM observer is used by:

  • Editor View DOM: Detects DOM changes for model synchronization
  • Collaboration: Tracks changes for sync
  • Text Analyzer: Provides text change data

When to Use​

  • DOM Change Detection: Monitor DOM mutations
  • Model Synchronization: Sync DOM changes to model
  • Collaborative Editing: Track changes for sync
  • Change Tracking: Monitor document modifications