GLSP-1531: Introduce viewport change event (#438)

* GLSP-1531: Introduce viewport change event

Fixes eclipse-glsp/glsp/issues/1531

* Address review feedback

Author: tortmayr

packages/client/src/base/command-stack.ts

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2019-2024 EclipseSource and others.
+ * Copyright (c) 2019-2025 EclipseSource and others.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
@@ -15,25 +15,37 @@
  ********************************************************************************/
 import {
     CommandExecutionContext,
+    CommandExecutionData,
     CommandStack,
     Disposable,
     DisposableCollection,
+    Emitter,
     Event,
     GModelRoot,
     ICommand,
-    LazyInjector,
-    SetModelCommand,
-    UpdateModelCommand
+    ICommandStack,
+    LazyInjector
 } from '@eclipse-glsp/sprotty';
-import { inject, injectable, preDestroy } from 'inversify';
+import { inject, injectable, postConstruct, preDestroy } from 'inversify';
 import { EditorContextService } from './editor-context-service';
 
 @injectable()
-export class GLSPCommandStack extends CommandStack implements Disposable {
+export class GLSPCommandStack extends CommandStack implements ICommandStack, Disposable {
     @inject(LazyInjector)
     protected lazyInjector: LazyInjector;
     protected toDispose = new DisposableCollection();
 
+    protected onCommandExecutedEmitter = new Emitter<CommandExecutionData>();
+    get onCommandExecuted(): Event<CommandExecutionData> {
+        return this.onCommandExecutedEmitter.event;
+    }
+
+    @postConstruct()
+    protected override initialize(): void {
+        super.initialize();
+        this.toDispose.push(this.onCommandExecutedEmitter);
+    }
+
     @preDestroy()
     dispose(): void {
         this.toDispose.dispose();
@@ -95,13 +107,7 @@ export class GLSPCommandStack extends CommandStack implements Disposable {
     }
     override async execute(command: ICommand): Promise<GModelRoot> {
         const result = await super.execute(command);
-        if (command instanceof SetModelCommand || command instanceof UpdateModelCommand) {
-            this.notifyListeners(result);
-        }
+        this.onCommandExecutedEmitter.fire({ command, newRoot: result });
         return result;
     }
-
-    protected notifyListeners(root: Readonly<GModelRoot>): void {
-        this.editorContext.notifyModelRootChanged(root, this);
-    }
 }

packages/client/src/base/default.module.ts

@@ -46,6 +46,7 @@ import { FocusStateChangedAction } from './focus/focus-state-change-action';
 import { FocusTracker } from './focus/focus-tracker';
 import { DiagramLoader } from './model/diagram-loader';
 import { GLSPModelSource } from './model/glsp-model-source';
+import { ModelChangeService } from './model/model-change-service';
 import { DefaultModelInitializationConstraint, ModelInitializationConstraint } from './model/model-initialization-constraint';
 import { GModelRegistry } from './model/model-registry';
 import { GLSPMousePositionTracker } from './mouse-position-tracker';
@@ -77,6 +78,7 @@ export const defaultModule = new FeatureModule(
         bind(TYPES.IEditorContextServiceProvider).toProvider<EditorContextService>(
             ctx => async () => ctx.container.get(EditorContextService)
         );
+        bind(TYPES.IModelChangeService).to(ModelChangeService).inSingletonScope();
 
         configureActionHandler(context, SetEditModeAction.KIND, EditorContextService);
         configureActionHandler(context, SetDirtyStateAction.KIND, EditorContextService);

packages/client/src/base/editor-context-service.ts

@@ -15,10 +15,8 @@
  ********************************************************************************/
 import {
     Action,
-    AnyObject,
     Args,
     Bounds,
-    CommandStack,
     Disposable,
     DisposableCollection,
     EditMode,
@@ -44,6 +42,7 @@ import {
 import { inject, injectable, postConstruct, preDestroy } from 'inversify';
 import { FocusChange, FocusTracker } from './focus/focus-tracker';
 import { IDiagramOptions, IDiagramStartup } from './model/diagram-loader';
+import { IModelChangeService, ViewportChange } from './model/model-change-service';
 import { SelectionChange, SelectionService } from './selection-service';
 
 /**
@@ -85,6 +84,9 @@ export class EditorContextService implements IActionHandler, Disposable, IDiagra
     @inject(SelectionService)
     protected selectionService: SelectionService;
 
+    @inject(TYPES.IModelChangeService)
+    protected modelChangeService: IModelChangeService;
+
     @inject(MousePositionTracker)
     protected mousePositionTracker: MousePositionTracker;
 
@@ -118,13 +120,11 @@ export class EditorContextService implements IActionHandler, Disposable, IDiagra
         return this.onDirtyStateChangedEmitter.event;
     }
 
-    protected _modelRoot?: Readonly<GModelRoot>;
     /**
      * Event that is fired when the model root of the diagram changes i.e. after the `CommandStack` has processed a model update.
      */
-    protected onModelRootChangedEmitter = new Emitter<Readonly<GModelRoot>>();
     get onModelRootChanged(): Event<Readonly<GModelRoot>> {
-        return this.onModelRootChangedEmitter.event;
+        return this.modelChangeService.onModelRootChanged;
     }
 
     /**
@@ -143,6 +143,14 @@ export class EditorContextService implements IActionHandler, Disposable, IDiagra
         return this.selectionService.onSelectionChanged;
     }
 
+    /**
+     * Event that is fired when the viewport of the diagram changes i.e. after the `CommandStack` has processed a viewport update.
+     * By default, this event is only fired if the viewport was changed via a `SetViewportCommand` or `BoundsAwareViewportCommand`
+     */
+    get onViewportChanged(): Event<ViewportChange> {
+        return this.modelChangeService.onViewportChanged;
+    }
+
     protected toDispose = new DisposableCollection();
 
     @postConstruct()
@@ -151,6 +159,11 @@ export class EditorContextService implements IActionHandler, Disposable, IDiagra
         this.toDispose.push(this.onEditModeChangedEmitter, this.onDirtyStateChangedEmitter);
     }
 
+    @preDestroy()
+    dispose(): void {
+        this.toDispose.dispose();
+    }
+
     preLoadDiagram(): MaybePromise<void> {
         this.lazyInjector.getAll<IGModelRootListener>(TYPES.IGModelRootListener).forEach(listener => {
             this.onModelRootChanged(event => listener.modelRootChanged(event));
@@ -160,11 +173,6 @@ export class EditorContextService implements IActionHandler, Disposable, IDiagra
         });
     }
 
-    @preDestroy()
-    dispose(): void {
-        this.toDispose.dispose();
-    }
-
     get(args?: Args): EditorContext {
         return {
             selectedElementIds: Array.from(this.selectionService.getSelectedElementIDs()),
@@ -181,21 +189,6 @@ export class EditorContextService implements IActionHandler, Disposable, IDiagra
         };
     }
 
-    /**
-     * Notifies the service about a model root change. This method should not be called
-     * directly. It is called by the `CommandStack` after a model update has been processed.
-     * @throws an error if the notifier is not a `CommandStack`
-     * @param root the new model root
-     * @param notifier the object that triggered the model root change
-     */
-    notifyModelRootChanged(root: Readonly<GModelRoot>, notifier: AnyObject): void {
-        if (!(notifier instanceof CommandStack)) {
-            throw new Error('Invalid model root change notification. Notifier is not an instance of `CommandStack`.');
-        }
-        this._modelRoot = root;
-        this.onModelRootChangedEmitter.fire(root);
-    }
-
     handle(action: Action): void {
         if (SetEditModeAction.is(action)) {
             this.handleSetEditModeAction(action);
@@ -234,14 +227,14 @@ export class EditorContextService implements IActionHandler, Disposable, IDiagra
     }
 
     get modelRoot(): Readonly<GModelRoot> {
-        if (!this._modelRoot) {
+        if (!this.modelChangeService.currentRoot) {
             throw new Error('Model root not available yet');
         }
-        return this._modelRoot;
+        return this.modelChangeService.currentRoot;
     }
 
     get viewport(): Readonly<GModelRoot & Viewport> | undefined {
-        return this._modelRoot ? findParentByFeature(this._modelRoot, isViewport) : undefined;
+        return this.modelRoot ? findParentByFeature(this.modelRoot, isViewport) : undefined;
     }
 
     get viewportData(): Readonly<Viewport> {
@@ -255,7 +248,7 @@ export class EditorContextService implements IActionHandler, Disposable, IDiagra
 
     get canvasBounds(): Readonly<Bounds> {
         // default value aligned with the initialization of canvasBounds in GModelRoot
-        return this._modelRoot?.canvasBounds ?? Bounds.EMPTY;
+        return this.modelRoot?.canvasBounds ?? Bounds.EMPTY;
     }
 
     get selectedElements(): Readonly<GModelElement>[] {

packages/client/src/base/focus/focus-tracker.ts

@@ -13,8 +13,8 @@
  *
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
-import { Action, Emitter, Event, IActionHandler, ICommand, TYPES, ViewerOptions } from '@eclipse-glsp/sprotty';
-import { inject, injectable } from 'inversify';
+import { Action, Disposable, Emitter, Event, IActionHandler, ICommand, TYPES, ViewerOptions } from '@eclipse-glsp/sprotty';
+import { inject, injectable, preDestroy } from 'inversify';
 import { FocusStateChangedAction } from './focus-state-change-action';
 
 export interface FocusChange {
@@ -29,7 +29,7 @@ export interface FocusChange {
  * Allows querying of the current focus state and the focused root diagram element and the currently focused element within the diagram.
  */
 @injectable()
-export class FocusTracker implements IActionHandler {
+export class FocusTracker implements IActionHandler, Disposable {
     protected inActiveCssClass = 'inactive';
     protected _hasFocus = true;
     protected _focusElement: HTMLOrSVGElement | null;
@@ -77,4 +77,9 @@ export class FocusTracker implements IActionHandler {
         }
         this.onFocusChangedEmitter.fire({ hasFocus: this.hasFocus, focusElement: this.focusElement, diagramElement: this.diagramElement });
     }
+
+    @preDestroy()
+    dispose(): void {
+        this.onFocusChangedEmitter.dispose();
+    }
 }

packages/client/src/base/model/model-change-service.ts

@@ -0,0 +1,151 @@
+/********************************************************************************
+ * Copyright (c) 2025 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+import {
+    BoundsAwareViewportCommand,
+    Disposable,
+    DisposableCollection,
+    Emitter,
+    Event,
+    GModelRoot,
+    ICommand,
+    ICommandStack,
+    LazyInjector,
+    SetModelCommand,
+    SetViewportCommand,
+    TYPES,
+    UpdateModelCommand,
+    Viewport,
+    almostEquals,
+    isViewport
+} from '@eclipse-glsp/sprotty';
+import { inject, postConstruct, preDestroy } from 'inversify';
+
+/**
+ * Service that tracks changes to the model root and the viewport.
+ * Allows to register listeners that are notified when the model root or the viewport changes.
+ * The current model root can be queried at any time.
+ */
+export interface IModelChangeService {
+    /** The current model root */
+    readonly currentRoot: Readonly<GModelRoot> | undefined;
+    /**
+     * Event that is fired when the model root of the diagram changes i.e. after the `CommandStack` has processed a model update.
+     */
+    onModelRootChanged: Event<Readonly<GModelRoot>>;
+
+    /**
+     * Event that is fired when the viewport of the diagram changes i.e. after the `CommandStack` has processed a viewport update.
+     * By default, this event is only fired if the viewport was changed via a `SetViewportCommand` or `BoundsAwareViewportCommand`
+     */
+    onViewportChanged: Event<ViewportChange>;
+}
+
+/**
+ * Event data for the {@link IModelChangeService.onViewportChanged} event.
+ */
+export interface ViewportChange {
+    /** The new viewport */
+    newViewport: Readonly<Viewport>;
+    /** The old viewport */
+    oldViewport?: Readonly<Viewport>;
+}
+
+export class ModelChangeService implements IModelChangeService, Disposable {
+    @inject(LazyInjector)
+    protected lazyInjector: LazyInjector;
+    protected _currentRoot?: Readonly<GModelRoot>;
+    protected lastViewport?: Readonly<Viewport>;
+    protected toDispose = new DisposableCollection();
+
+    get currentRoot(): Readonly<GModelRoot> | undefined {
+        return this._currentRoot;
+    }
+
+    protected get commandStack(): ICommandStack {
+        return this.lazyInjector.get<ICommandStack>(TYPES.ICommandStack);
+    }
+
+    protected onModelRootChangedEmitter = new Emitter<Readonly<GModelRoot>>();
+    get onModelRootChanged(): Event<Readonly<GModelRoot>> {
+        return this.onModelRootChangedEmitter.event;
+    }
+
+    protected onViewportChangedEmitter = new Emitter<ViewportChange>();
+    get onViewportChanged(): Event<ViewportChange> {
+        return this.onViewportChangedEmitter.event;
+    }
+
+    @postConstruct()
+    protected initialize(): void {
+        this.toDispose.push(this.onModelRootChangedEmitter, this.onViewportChangedEmitter);
+        this.commandStack.onCommandExecuted(data => this.handleCommandExecution(data.command, data.newRoot));
+    }
+
+    @preDestroy()
+    dispose(): void {
+        this.toDispose.dispose();
+    }
+
+    protected handleCommandExecution(command: ICommand, newRoot: GModelRoot): void {
+        if (this.isModelRootChangeCommand(command)) {
+            this.handleModelRootChangeCommand(command, newRoot);
+        }
+        if (this.isViewportChangeCommand(command)) {
+            this.handleViewportChangeCommand(command, newRoot);
+        }
+    }
+
+    protected isModelRootChangeCommand(command: ICommand): boolean {
+        return command instanceof SetModelCommand || command instanceof UpdateModelCommand;
+    }
+
+    protected isViewportChangeCommand(command: ICommand): boolean {
+        return command instanceof SetViewportCommand || command instanceof BoundsAwareViewportCommand;
+    }
+
+    protected handleModelRootChangeCommand(command: ICommand, newRoot: GModelRoot): void {
+        this._currentRoot = newRoot;
+        this.lastViewport = this.toViewport(newRoot);
+        this.onModelRootChangedEmitter.fire(newRoot);
+    }
+
+    protected handleViewportChangeCommand(command: ICommand, newRoot: GModelRoot): void {
+        const viewport = this.toViewport(newRoot);
+        if (!viewport) {
+            return;
+        }
+
+        if (this.hasViewportChanged(viewport)) {
+            this.onViewportChangedEmitter.fire({ newViewport: viewport, oldViewport: this.lastViewport });
+            this.lastViewport = viewport;
+        }
+    }
+
+    protected hasViewportChanged(newViewport: Readonly<Viewport>): boolean {
+        if (!this.lastViewport) {
+            return true;
+        }
+        return !(
+            almostEquals(newViewport.zoom, this.lastViewport.zoom) &&
+            almostEquals(newViewport.scroll.x, this.lastViewport.scroll.x) &&
+            almostEquals(newViewport.scroll.y, this.lastViewport.scroll.y)
+        );
+    }
+
+    protected toViewport(root: Readonly<GModelRoot>): Readonly<Viewport> | undefined {
+        return isViewport(root) ? { scroll: root.scroll, zoom: root.zoom } : undefined;
+    }
+}