fix(editor): only fire change event on non-programmatic changes

Author: e111077

README.md

@@ -811,6 +811,12 @@ project element.
 | `editor`             | `string \| PlaygroundFileEditor` | `undefined` | The editor this bar controls. Either the `<playground-file-editor>` itself, or its `id` in the host scope.        |
 | `editableFileSystem` | `boolean`                        | `false`     | Allow adding, removing, and renaming files                                                                        |
 
+### Events
+
+| Event       | Description               |
+| ----------- | ------------------------- |
+| `tabchange` | A tab has been activated. |
+
 ---
 
 ## `<playground-file-editor>`
@@ -861,9 +867,9 @@ A pure text editor based on CodeMirror with syntax highlighting for HTML, CSS, J
 
 ### Events
 
-| Event    | Description                          |
-| -------- | ------------------------------------ |
-| `change` | User made an edit to the active file |
+| Event    | Description                                                                                                                                        |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `change` | User made an edit to the active file (note: this event is not fired for programmatic changes to the value property nor for the user changing tabs) |
 
 ### Keyboard shortcuts
 

src/internal/tab-bar.ts

@@ -80,6 +80,7 @@ export class PlaygroundInternalTabBar extends LitElement {
         new CustomEvent<{tab?: PlaygroundInternalTab}>('tabchange', {
           detail: {tab: undefined},
           bubbles: true,
+          composed: true,
         })
       );
     }

src/internal/tab.ts

@@ -106,6 +106,7 @@ export class PlaygroundInternalTab extends LitElement {
         new CustomEvent<{tab?: PlaygroundInternalTab}>('tabchange', {
           detail: {tab: this},
           bubbles: true,
+          composed: true,
         })
       );
     }

src/playground-code-editor.ts

@@ -339,7 +339,8 @@ export class PlaygroundCodeEditor extends LitElement {
   @queryAssignedElements({slot: 'extensions', flatten: true})
   private _extensionElements!: HTMLElement[];
 
-  private _valueChangingFromOutside = false;
+  // Annotation to mark programmatic changes (not user edits)
+  private readonly _programmaticChange = Annotation.define<boolean>();
   private _diagnosticDecorations: DecorationSet = Decoration.none;
   private _diagnosticsMouseoverListenerActive = false;
   private _lastTransactions: Transaction[] = [];
@@ -424,6 +425,7 @@ export class PlaygroundCodeEditor extends LitElement {
                     insert: this.value ?? '',
                   },
                 ],
+                annotations: this._programmaticChange.of(true),
               });
             }
           }
@@ -447,14 +449,13 @@ export class PlaygroundCodeEditor extends LitElement {
                   insert: this.value ?? '',
                 },
               ],
+              annotations: this._programmaticChange.of(true),
             });
             docState = tempView.state;
             this._docCache.set(docKey, docState);
             tempView.destroy();
           }
 
-          this._valueChangingFromOutside = true;
-
           // Replace the entire view with the new editor state. Unlike CM5, CM6
           // is modular, and the history stays on the state object rather than
           // the editor / view.
@@ -465,8 +466,6 @@ export class PlaygroundCodeEditor extends LitElement {
           if (needsHideAndFold) {
             void this._applyHideAndFoldRegions();
           }
-
-          this._valueChangingFromOutside = false;
           break;
         }
         case 'value':
@@ -476,8 +475,6 @@ export class PlaygroundCodeEditor extends LitElement {
           }
 
           if (this.value !== view?.state.doc.toString()) {
-            this._valueChangingFromOutside = true;
-
             // The 'value' property was changed externally and it differs from
             // the editor's current document content, so we need to update the
             // view model to match.
@@ -492,9 +489,8 @@ export class PlaygroundCodeEditor extends LitElement {
                   insert: this.value ?? '',
                 },
               ],
+              annotations: this._programmaticChange.of(true),
             });
-
-            this._valueChangingFromOutside = false;
           }
           break;
         case 'lineNumbers':
@@ -720,9 +716,14 @@ export class PlaygroundCodeEditor extends LitElement {
               tr.annotation(Transaction.userEvent) === 'redo'
           );
 
+          // Check if this change was programmatic (not a user edit)
+          const isProgrammatic = update.transactions.some(
+            (tr) => tr.annotation(this._programmaticChange) === true
+          );
+
           // External changes are usually things like the editor switching which
           // file it is displaying.
-          if (this._valueChangingFromOutside) {
+          if (isProgrammatic) {
             // Apply hide/fold regions when value changes from outside
             void this._applyHideAndFoldRegions();
             this._showDiagnostics();
@@ -731,6 +732,7 @@ export class PlaygroundCodeEditor extends LitElement {
               // Always reapply hide/fold regions after undo/redo
               void this._applyHideAndFoldRegions();
             }
+            // Only fire change event for user-initiated edits
             this.dispatchEvent(new Event('change'));
           }
         }

src/test/playground-code-editor_test.ts

@@ -73,6 +73,129 @@ suite('playground-code-editor', () => {
     });
   });
 
+  test('does NOT dispatch change event when switching documentKey and value together', async () => {
+    const editor = document.createElement('playground-code-editor');
+    const DOCUMENT_KEY1 = {doc: 1};
+    const DOCUMENT_KEY2 = {doc: 2};
+
+    editor.value = 'document 1';
+    editor.documentKey = DOCUMENT_KEY1;
+    container.appendChild(editor);
+    await editor.updateComplete;
+    await raf();
+
+    let changeCount = 0;
+    editor.addEventListener('change', () => {
+      changeCount++;
+    });
+
+    // This simulates what playground-file-editor does when switching files
+    // Both value AND documentKey change together in a single update
+    editor.value = 'document 2';
+    editor.documentKey = DOCUMENT_KEY2;
+
+    // Wait for Lit's update cycle
+    await editor.updateComplete;
+    await raf();
+
+    // Wait for any potential async change events
+    await wait(100);
+
+    // Switch back - this is where the bug manifests in lit.dev
+    editor.value = 'document 1 modified';
+    editor.documentKey = DOCUMENT_KEY1;
+    await editor.updateComplete;
+    await raf();
+    await wait(100);
+
+    assert.equal(
+      changeCount,
+      0,
+      'Switching documentKey and value together should not fire change event'
+    );
+  });
+
+  test('does NOT dispatch change event when switching documentKey', async () => {
+    const editor = document.createElement('playground-code-editor');
+    const DOCUMENT_KEY1 = {dockey: 1};
+    const DOCUMENT_KEY2 = {dockey: 2};
+
+    editor.value = 'document 1';
+    editor.documentKey = DOCUMENT_KEY1;
+    container.appendChild(editor);
+    await editor.updateComplete;
+    await raf();
+
+    let changeCount = 0;
+    editor.addEventListener('change', () => changeCount++);
+
+    // Switch to a different document - should NOT fire change event
+    editor.value = 'document 2';
+    editor.documentKey = DOCUMENT_KEY2;
+    await editor.updateComplete;
+    await raf();
+
+    assert.equal(
+      changeCount,
+      0,
+      'Switching documentKey should not fire change event'
+    );
+
+    // Switch back to first document - should NOT fire change event
+    editor.value = 'document 1';
+    editor.documentKey = DOCUMENT_KEY1;
+    await editor.updateComplete;
+    await raf();
+
+    assert.equal(
+      changeCount,
+      0,
+      'Switching back to original documentKey should not fire change event'
+    );
+  });
+
+  test('dispatches change event only for user edits, not programmatic changes', async () => {
+    const editor = document.createElement('playground-code-editor');
+    editor.value = 'foo';
+    container.appendChild(editor);
+    await editor.updateComplete;
+    await raf();
+
+    const editorInternals = editor as unknown as {
+      _editorView: EditorView;
+    };
+
+    let changeCount = 0;
+    editor.addEventListener('change', () => changeCount++);
+
+    // Programmatic change - should NOT fire
+    editor.value = 'bar';
+    await editor.updateComplete;
+    await raf();
+    assert.equal(changeCount, 0, 'No change event after programmatic update');
+
+    // User edit via CodeMirror - SHOULD fire
+    editorInternals._editorView.dispatch({
+      changes: {
+        from: 0,
+        to: editorInternals._editorView.state.doc.length,
+        insert: 'baz',
+      },
+    });
+    await raf();
+    assert.equal(changeCount, 1, 'Change event fired after user edit');
+
+    // Another programmatic change - should NOT fire
+    editor.value = 'qux';
+    await editor.updateComplete;
+    await raf();
+    assert.equal(
+      changeCount,
+      1,
+      'No additional change event after another programmatic update'
+    );
+  });
+
   suite('history', () => {
     let editor: PlaygroundCodeEditor;
     let editorInternals: {