@eclipse-glsp/client 1.1.0-next.383e4e9.264 → 1.1.0-next.3d1b3e6.280

package/src/base/model/glsp-model-source.ts

@@ -0,0 +1,199 @@
+/********************************************************************************
+ * Copyright (c) 2023 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 { inject, injectable, preDestroy } from 'inversify';
+import {
+    Action,
+    ActionMessage,
+    Disposable,
+    DisposableCollection,
+    DisposeClientSessionParameters,
+    GLSPClient,
+    ILogger,
+    InitializeClientSessionParameters,
+    InitializeResult,
+    ModelSource,
+    SModelRootSchema,
+    TYPES
+} from '~glsp-sprotty';
+import { GLSPActionHandlerRegistry } from '../action-handler-registry';
+import { IDiagramOptions } from './diagram-loader';
+/**
+ * A helper interface that allows the client to mark actions that have been received from the server.
+ */
+export interface ServerAction extends Action {
+    __receivedFromServer: true;
+}
+
+export namespace ServerAction {
+    export function is(object: unknown): object is ServerAction {
+        return Action.is(object) && '__receivedFromServer' in object && object.__receivedFromServer === true;
+    }
+
+    /**
+     * Mark the given action as {@link ServerAction} by attaching the "_receivedFromServer" property
+     * @param action The action that should be marked as server action
+     */
+    export function mark(action: Action): void {
+        (action as ServerAction).__receivedFromServer = true;
+    }
+}
+
+/**
+ * Central component for enabling the client-server action flow with the help of an underlying {@link GLSPClient}.
+ * Handles & forwards actions that are intended for the GLSP server. In addition, it handles {@link ActionMessage}s received
+ * from the server and dispatches the corresponding actions locally.
+ *
+ * Note that in sprotty a {@link ModelSource} is serving the model to the event cycle and
+ * is used to commit the local (i.e. client-side) model back to the source.
+ * However, in GLSP the update flow is reversed meaning that changes to the source model are applied
+ * on the server side and then an update is sent to the client.
+ */
+@injectable()
+export class GLSPModelSource extends ModelSource implements Disposable {
+    @inject(TYPES.ILogger)
+    protected logger: ILogger;
+
+    @inject(TYPES.IDiagramOptions)
+    protected options: IDiagramOptions;
+
+    protected toDispose = new DisposableCollection();
+    clientId: string;
+
+    protected _currentRoot: SModelRootSchema;
+    protected registry: GLSPActionHandlerRegistry;
+    protected glspClient?: GLSPClient;
+
+    get diagramType(): string {
+        return this.options.diagramType;
+    }
+
+    get sourceUri(): string | undefined {
+        return this.options.sourceUri;
+    }
+
+    /**
+     * Configure forwarding of server-handled actions to the given {@link GLSPClient} and
+     * handling of action received from the `GLSPClient` (i.e. server). It is expected that the
+     * given GLSP client has already been initialized.
+     * @param glspClient The GLSP  to use.
+     * @throws An error if the given `GLSPClient` has not been initialized yet or if the set of server handled
+     *         action kinds could not be derived from the initialize result
+     */
+    configure(glspClient: GLSPClient): Promise<void> {
+        this.glspClient = glspClient;
+        if (!glspClient.initializeResult) {
+            throw new Error('Could not configure model source. The GLSP client is not initialized yet!');
+        }
+
+        const initializeParams = this.createInitializeClientSessionParameters(glspClient.initializeResult);
+        this.configureServeActions(glspClient.initializeResult);
+
+        this.toDispose.push(
+            glspClient.onActionMessage(message => this.messageReceived(message), this.clientId),
+            Disposable.create(() => glspClient.disposeClientSession(this.createDisposeClientSessionParameters()))
+        );
+
+        return glspClient!.initializeClientSession(initializeParams);
+    }
+
+    protected createInitializeClientSessionParameters(_initializeResult: InitializeResult): InitializeClientSessionParameters {
+        const clientActionKinds = this.registry.getHandledActionKinds();
+        return {
+            clientSessionId: this.clientId,
+            clientActionKinds,
+            diagramType: this.diagramType
+        };
+    }
+
+    protected createDisposeClientSessionParameters(): DisposeClientSessionParameters {
+        return {
+            clientSessionId: this.clientId
+        };
+    }
+
+    protected configureServeActions(initializeResult: InitializeResult): void {
+        const serverActions = initializeResult.serverActions[this.diagramType];
+        if (serverActions?.length === 0) {
+            throw new Error(`No server-handled actions could be derived from the initialize result for diagramType: ${this.diagramType}!`);
+        }
+        serverActions.forEach(action => this.registry.register(action, this));
+    }
+
+    protected messageReceived(message: ActionMessage): void {
+        if (this.clientId !== message.clientId) {
+            return;
+        }
+        const action = message.action;
+        ServerAction.mark(action);
+        this.logger.log(this, 'receiving', action);
+        this.actionDispatcher.dispatch(action);
+    }
+
+    override initialize(registry: GLSPActionHandlerRegistry): void {
+        // Registering actions here is discouraged and it's recommended
+        // to implemented dedicated action handlers.
+        if (!this.clientId) {
+            this.clientId = this.options.clientId ?? this.viewerOptions.baseDiv;
+        }
+
+        this.registry = registry;
+    }
+
+    handle(action: Action): void {
+        // Handling additional actions here is discouraged and it's recommended
+        // to implemented dedicated action handlers.
+        if (this.shouldForwardToServer(action)) {
+            this.forwardToServer(action);
+        }
+    }
+
+    protected forwardToServer(action: Action): void {
+        const message: ActionMessage = {
+            clientId: this.clientId,
+            action: action
+        };
+        this.logger.log(this, 'sending', message);
+        if (this.glspClient) {
+            this.glspClient.sendActionMessage(message);
+        } else {
+            throw new Error('GLSPClient is not connected');
+        }
+    }
+
+    protected shouldForwardToServer(action: Action): boolean {
+        return !ServerAction.is(action);
+    }
+
+    commitModel(newRoot: SModelRootSchema): SModelRootSchema {
+        /* In GLSP the model update flow is server-driven. i.e. changes to the graphical model are applied
+         * on server-side an only the server can issue a model update.
+         * The internal/local model should never be committed back to the model source i.e. GLSP server.
+         * => no-op implementation that simply returns the `newRoot`
+         */
+        this._currentRoot = newRoot;
+        return newRoot;
+    }
+
+    override get model(): SModelRootSchema {
+        return this._currentRoot;
+    }
+
+    @preDestroy()
+    dispose(): void {
+        this.toDispose.dispose();
+    }
+}

package/src/base/model/model-initialization-constraint.spec.ts

@@ -0,0 +1,95 @@
+/********************************************************************************
+ * Copyright (c) 2023 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 { expect } from 'chai';
+import { Container } from 'inversify';
+import 'reflect-metadata';
+import * as sinon from 'sinon';
+import { Deferred, EMPTY_ROOT, InitializeCanvasBoundsAction, SetModelAction, UpdateModelAction } from '~glsp-sprotty';
+import { DefaultModelInitializationConstraint, ModelInitializationConstraint } from './model-initialization-constraint';
+const sandbox = sinon.createSandbox();
+const container = new Container();
+let constraint: ModelInitializationConstraint;
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+const listener = sandbox.spy((): void => {});
+
+describe('DefaultModelInitializationConstraint', () => {
+    beforeEach(() => {
+        constraint = container.resolve(DefaultModelInitializationConstraint);
+        sandbox.reset();
+    });
+    it('should complete after dispatching  non empty SetModelAction and `InitializeCanvasBoundsAction`', () => {
+        expect(constraint.isCompleted).to.be.false;
+        constraint.notifyDispatched(SetModelAction.create({ id: 'model', type: 'graph' }));
+        expect(constraint.isCompleted).to.be.false;
+        constraint.notifyDispatched({ kind: InitializeCanvasBoundsAction.KIND });
+        expect(constraint.isCompleted).to.be.true;
+    });
+    it('should complete after dispatching non empty UpdateModelAction and `InitializeCanvasBoundsAction`', () => {
+        expect(constraint.isCompleted).to.be.false;
+        constraint.notifyDispatched(UpdateModelAction.create({ id: 'model', type: 'graph' }));
+        expect(constraint.isCompleted).to.be.false;
+        constraint.notifyDispatched({ kind: InitializeCanvasBoundsAction.KIND });
+        expect(constraint.isCompleted).to.be.true;
+    });
+    it('should note complete after dispatching empty SetModelAction and `InitializeCanvasBoundsAction` ', () => {
+        expect(constraint.isCompleted).to.be.false;
+        constraint.notifyDispatched(SetModelAction.create(EMPTY_ROOT));
+        expect(constraint.isCompleted).to.be.false;
+        constraint.notifyDispatched({ kind: InitializeCanvasBoundsAction.KIND });
+        expect(constraint.isCompleted).to.be.false;
+    });
+    it('should note complete after dispatching  empty UpdateModelAction and `InitializeCanvasBoundsAction ', () => {
+        expect(constraint.isCompleted).to.be.false;
+        constraint.notifyDispatched(UpdateModelAction.create(EMPTY_ROOT));
+        expect(constraint.isCompleted).to.be.false;
+        constraint.notifyDispatched({ kind: InitializeCanvasBoundsAction.KIND });
+        expect(constraint.isCompleted).to.be.false;
+    });
+    describe('onInitialized', () => {
+        it('returned promise should resolve once the constraint is initialized', async () => {
+            const initializeDeferred = new Deferred<void>();
+            const initializePromise = constraint.onInitialized();
+            initializePromise.then(() => initializeDeferred.resolve());
+            expect(initializeDeferred.state).to.be.equal('unresolved');
+            // Directly trigger the completion method simplify test logic
+            constraint['setCompleted']();
+            // Short delay of test execution to ensure that the deferred state is updated.
+            await new Promise(resolve => setTimeout(resolve, 5));
+            expect(initializeDeferred.state).to.be.equal('resolved');
+        });
+        it('registered listener should be invoked once the constraint is initialized', () => {
+            constraint.onInitialized(listener);
+            expect(listener.called).to.be.false;
+            // Directly trigger the completion method simplify test logic
+            constraint['setCompleted']();
+            expect(listener.called).to.be.true;
+        });
+        it('registered listener should be invoked directly on registration if the constraint is already initialized', () => {
+            // Directly trigger the completion method simplify test logic
+            constraint['setCompleted']();
+            constraint.onInitialized(listener);
+            expect(listener.called).to.be.true;
+        });
+        it('Disposed listener should not be invoked once the constraint is initialized', () => {
+            const toDispose = constraint.onInitialized(listener);
+            expect(listener.called).to.be.false;
+            toDispose.dispose();
+            // Directly trigger the completion method simplify test logic
+            constraint['setCompleted']();
+            expect(listener.called).to.be.false;
+        });
+    });
+});

package/src/base/{model-initialization-constraint.ts → model/model-initialization-constraint.ts}

@@ -14,7 +14,7 @@
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
 import { injectable } from 'inversify';
-import { Action, Deferred, InitializeCanvasBoundsAction, SetModelAction, UpdateModelAction } from '~glsp-sprotty';
+import { Action, Deferred, Disposable, Emitter, InitializeCanvasBoundsAction, SetModelAction, UpdateModelAction } from '~glsp-sprotty';
 
 /**
  * The constraint defining when the initialization of the GLSP model is completed.
@@ -37,21 +37,46 @@ import { Action, Deferred, InitializeCanvasBoundsAction, SetModelAction, UpdateM
 @injectable()
 export abstract class ModelInitializationConstraint {
     protected completion: Deferred<void> = new Deferred();
-    protected completed = false;
 
+    protected _isCompleted = false;
     get isCompleted(): boolean {
-        return this.completed;
+        return this._isCompleted;
     }
 
-    protected setCompleted(isCompleted: boolean): void {
-        this.completed = isCompleted;
-        if (isCompleted) {
-            this.completion.resolve();
+    protected onInitializedEmitter = new Emitter<void>();
+
+    /**
+     * Register a listener that will be invoked once the initialization process
+     * has been completed. If the initialization is already completed on registration
+     * the given listener will be invoked right away
+     * @param listener
+     */
+    onInitialized(listener: () => void): Disposable;
+
+    /**
+     * Retrieve a promise that resolves once the initialization process
+     * has been completed.
+     * @returns the initialization promise
+     */
+    onInitialized(): Promise<void>;
+    onInitialized(listener?: () => void): Promise<void> | Disposable {
+        if (!listener) {
+            return this.completion.promise;
         }
+        if (this.isCompleted) {
+            listener();
+            return Disposable.empty();
+        }
+        return this.onInitializedEmitter.event(listener);
     }
 
-    onInitialized(): Promise<void> {
-        return this.completion.promise;
+    protected setCompleted(): void {
+        if (!this.isCompleted) {
+            this._isCompleted = true;
+            this.completion.resolve();
+            this.onInitializedEmitter.fire();
+            this.onInitializedEmitter.dispose();
+        }
     }
 
     notifyDispatched(action: Action): void {
@@ -59,10 +84,18 @@ export abstract class ModelInitializationConstraint {
             return;
         }
         if (this.isInitializedAfter(action)) {
-            this.setCompleted(true);
+            this.setCompleted();
         }
     }
 
+    /**
+     * Central method to check the initialization state. Is invoked
+     * for every action dispatched by the `ActionDispatcher` (until the initialization has completed).
+     *  Should
+     * return `true` once the action has been passed which marks the end
+     * of the initialization process.
+     * @param action The last dispatched action
+     */
     abstract isInitializedAfter(action: Action): boolean;
 }
 

package/src/base/selection-service.spec.ts

@@ -16,7 +16,7 @@
 import { AssertionError, expect } from 'chai';
 import { Container, injectable } from 'inversify';
 import * as sinon from 'sinon';
-import { Action, Disposable, SGraphFactory, SModelElementSchema, SModelRoot, TYPES, initializeContainer } from '~glsp-sprotty';
+import { Action, Disposable, SGraphFactory, SModelRoot, SNode, TYPES, initializeContainer } from '~glsp-sprotty';
 import { defaultModule } from './default.module';
 import { IFeedbackActionDispatcher, IFeedbackEmitter } from './feedback/feedback-action-dispatcher';
 import { ISelectionListener, SelectFeedbackAction, SelectionService } from './selection-service';
@@ -62,7 +62,6 @@ function createContainer(): Container {
 
 describe('SelectionService', () => {
     // eslint-disable-next-line deprecation/deprecation
-    let graphFactory: SGraphFactory;
     let root: SModelRoot;
     let selectionService: SelectionService;
     let feedbackDispatcher: MockFeedbackActionDispatcher;
@@ -70,7 +69,6 @@ describe('SelectionService', () => {
     beforeEach(() => {
         const container = createContainer();
         // eslint-disable-next-line deprecation/deprecation
-        graphFactory = container.get<SGraphFactory>(TYPES.IModelFactory);
         root = createRoot('node1', 'node2', 'node3', 'node4', 'node5');
         selectionService = container.get<SelectionService>(SelectionService);
         feedbackDispatcher = container.get<MockFeedbackActionDispatcher>(TYPES.IFeedbackActionDispatcher);
@@ -243,13 +241,16 @@ describe('SelectionService', () => {
     });
 
     function createRoot(...nodes: string[]): SModelRoot {
-        const children: SModelElementSchema[] = [];
-        nodes.forEach(node => children.push({ id: node, type: 'node:circle' }));
-        return graphFactory.createRoot({
-            id: 'selection-service-spec',
-            type: 'graph',
-            children: children
+        const model = new SModelRoot();
+        model.id = 'selection-service-spec';
+        model.type = 'graph';
+        nodes.forEach(id => {
+            const node = new SNode();
+            node.type = 'node:circle';
+            node.id = id;
+            model.add(node);
         });
+        return model;
     }
 
     function assertSelectionAndFeedback(expectedSelection: string[], expectedDeselection: string[]): void {

package/src/base/tool-manager/tool-manager.ts

@@ -0,0 +1,183 @@
+/********************************************************************************
+ * Copyright (c) 2019-2023 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 { inject, injectable, multiInject, optional } from 'inversify';
+import {
+    Action,
+    EditMode,
+    IActionHandler,
+    ICommand,
+    KeyListener,
+    SModelElement,
+    TYPES,
+    distinctAdd,
+    matchesKeystroke
+} from '~glsp-sprotty';
+import { EditorContextService, EditorContextServiceProvider } from '../editor-context-service';
+import { EnableDefaultToolsAction, EnableToolsAction, Tool } from './tool';
+/**
+ * A tool manager coordinates the state of tools in the context of an editor.
+ *
+ * One instance of a tool manager is intended per editor, coordinating the state of all tools within
+ * this editor. A tool can be active or not. A tool manager ensures that activating a set of tools
+ * will disable all other tools, allowing them to invoke behavior when they become enabled or disabled.
+ */
+export interface IToolManager {
+    /** All tools managed by this tool manager. */
+    readonly managedTools: Tool[];
+
+    /** The tools that are enabled by default, whenever no other tool is enabled. */
+    readonly defaultTools: Tool[];
+
+    /** The currently active tools, which are either specifically enabled tools, or the default tools. */
+    readonly activeTools: Tool[];
+
+    /**
+     * Enables the tools with the specified `toolIds`.
+     * Therefore, this manager first disables currently active tools and then enable the
+     * tools indicated in `toolIds`, making them the currently active tools. If this manager
+     * doesn't manage one or more tools specified in `toolIds`, it'll do nothing. If not a
+     * single tool that shall be enabled was found in the managed tools, it'll fall back to
+     * the default tools.
+     *
+     * @param tools The tools to be enabled.
+     */
+    enable(toolIds: string[]): void;
+
+    /**
+     * Enables all default tools.
+     */
+    enableDefaultTools(): void;
+
+    /** Disables all currently active tools. After this call, no tool will be active anymore. */
+    disableActiveTools(): void;
+
+    registerDefaultTools(...tools: Tool[]): void;
+
+    registerTools(...tools: Tool[]): void;
+}
+
+/**
+ * The default {@link IToolManager} implementation. Allows
+ * registration of tools via Dependency Injection.
+ */
+@injectable()
+export class ToolManager implements IToolManager {
+    readonly actives: Tool[] = [];
+
+    protected editorContext?: EditorContextService;
+
+    constructor(
+        @multiInject(TYPES.ITool)
+        @optional()
+        readonly tools: Tool[] = [],
+        @multiInject(TYPES.IDefaultTool)
+        @optional()
+        readonly defaultTools: Tool[],
+        @inject(TYPES.IEditorContextServiceProvider) protected contextServiceProvider: EditorContextServiceProvider
+    ) {
+        this.registerTools(...this.tools);
+        this.registerDefaultTools(...this.defaultTools);
+        this.enableDefaultTools();
+        this.contextServiceProvider().then(editorContext => {
+            editorContext.onEditModeChanged(change => this.editModeChanged(change.newValue, change.oldValue));
+            this.editorContext = editorContext;
+        });
+    }
+
+    get managedTools(): Tool[] {
+        return this.defaultTools.concat(this.tools);
+    }
+
+    get activeTools(): Tool[] {
+        return this.actives;
+    }
+
+    registerDefaultTools(...tools: Tool[]): void {
+        distinctAdd(this.defaultTools, ...tools);
+    }
+
+    registerTools(...tools: Tool[]): void {
+        distinctAdd(this.tools, ...tools);
+    }
+
+    disableActiveTools(): void {
+        this.actives.forEach(tool => tool.disable());
+        this.actives.splice(0, this.actives.length);
+    }
+
+    enableDefaultTools(): void {
+        this.enable(this.defaultTools.map(tool => tool.id));
+    }
+
+    enable(toolIds: string[]): void {
+        this.disableActiveTools();
+        let tools = toolIds.map(id => this.tool(id));
+        if (this.editorContext && this.editorContext.isReadonly) {
+            tools = tools.filter(tool => !tool?.isEditTool);
+        }
+        tools.forEach(tool => {
+            if (tool !== undefined) {
+                tool.enable();
+                this.actives.push(tool);
+            }
+        });
+    }
+
+    tool(toolId: string): Tool | undefined {
+        return this.managedTools.find(tool => tool.id === toolId);
+    }
+
+    disableEditTools(): void {
+        this.disableActiveTools();
+        this.enable(this.defaultTools.filter(tool => !tool.isEditTool).map(tool => tool.id));
+    }
+
+    editModeChanged(newValue: string, oldValue: string): void {
+        if (oldValue === newValue) {
+            return;
+        }
+        if (newValue === EditMode.READONLY) {
+            this.disableEditTools();
+        } else if (newValue === EditMode.EDITABLE) {
+            this.enableDefaultTools();
+        }
+    }
+}
+
+@injectable()
+export class ToolManagerActionHandler implements IActionHandler {
+    @inject(TYPES.IToolManager)
+    readonly toolManager: IToolManager;
+
+    handle(action: Action): void | ICommand | Action {
+        if (EnableDefaultToolsAction.is(action)) {
+            this.toolManager.enableDefaultTools();
+        } else if (EnableToolsAction.is(action)) {
+            this.toolManager.enable((action as EnableToolsAction).toolIds);
+        }
+    }
+}
+
+@injectable()
+export class DefaultToolsEnablingKeyListener extends KeyListener {
+    override keyDown(element: SModelElement, event: KeyboardEvent): Action[] {
+        if (matchesKeystroke(event, 'Escape')) {
+            return [EnableDefaultToolsAction.create()];
+        }
+        return [];
+    }
+}