@eclipse-glsp/client 1.1.0-next.a07a5f7.197 → 1.1.0-next.a6d39b4.266

package/src/base/feedback/feedback-action-dispatcher.ts

@@ -0,0 +1,107 @@
+/********************************************************************************
+ * 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 } from 'inversify';
+import { Action, Disposable, IActionDispatcher, ILogger, TYPES } from '~glsp-sprotty';
+
+export interface IFeedbackEmitter {}
+
+/**
+ * Dispatcher for actions that are meant to show visual feedback on
+ * the diagram that is not part of the diagram sent from the server
+ * after a model update.
+ *
+ * The purpose of this dispatcher is to re-establish the feedback
+ * after the model has been updated or reset by the server, as this would
+ * overwrite the already established feedback, in case it is drawn by
+ * extending the `SModelRoot`. Therefore, tools can register themselves
+ * as feedback emitters with actions they want to place for showing
+ * feedback. This dispatcher will then re-establish all feedback actions
+ * of the registered emitters, whenever the `SModelRoot` has been set or updated.
+ */
+export interface IFeedbackActionDispatcher {
+    /**
+     * Registers `actions` to be sent out by a `feedbackEmitter`.
+     * @param feedbackEmitter the emitter sending out feedback actions.
+     * @param feedbackActions the actions to be sent out.
+     * @param cleanupActions the actions to be sent out when the feedback is de-registered through the returned Disposable.
+     * @returns A 'Disposable' that de-registers the feedback and cleans up any pending feedback with the given `cleanupActions`.
+     */
+    registerFeedback(feedbackEmitter: IFeedbackEmitter, feedbackActions: Action[], cleanupActions?: Action[]): Disposable;
+
+    /**
+     * Deregisters a `feedbackEmitter` from this dispatcher and thereafter
+     * dispatches the provided `actions`.
+     * @param feedbackEmitter the emitter to be deregistered.
+     * @param cleanupActions the actions to be dispatched right after the deregistration.
+     * These actions do not have to be related to the actions sent out by the
+     * deregistered `feedbackEmitter`. The purpose of these actions typically is
+     * to reset the normal state of the diagram without the feedback (e.g., reset a
+     * CSS class that was set by a feedbackEmitter).
+     */
+    deregisterFeedback(feedbackEmitter: IFeedbackEmitter, cleanupActions?: Action[]): void;
+
+    /**
+     * Retrieve all `actions` sent out by currently registered `feedbackEmitter`.
+     */
+    getRegisteredFeedback(): Action[];
+}
+
+@injectable()
+export class FeedbackActionDispatcher implements IFeedbackActionDispatcher {
+    protected registeredFeedback: Map<IFeedbackEmitter, Action[]> = new Map();
+
+    @inject(TYPES.IActionDispatcherProvider) protected actionDispatcher: () => Promise<IActionDispatcher>;
+    @inject(TYPES.ILogger) protected logger: ILogger;
+
+    registerFeedback(feedbackEmitter: IFeedbackEmitter, feedbackActions: Action[], cleanupActions?: Action[] | undefined): Disposable {
+        this.registeredFeedback.set(feedbackEmitter, feedbackActions);
+        this.dispatchFeedback(feedbackActions, feedbackEmitter);
+        return Disposable.create(() => this.deregisterFeedback(feedbackEmitter, cleanupActions));
+    }
+
+    deregisterFeedback(feedbackEmitter: IFeedbackEmitter, cleanupActions?: Action[] | undefined): void {
+        this.registeredFeedback.delete(feedbackEmitter);
+        if (cleanupActions) {
+            this.dispatchFeedback(cleanupActions, feedbackEmitter);
+        }
+    }
+
+    getRegisteredFeedback(): Action[] {
+        const result: Action[] = [];
+        this.registeredFeedback.forEach(actions => result.push(...actions));
+        return result;
+    }
+
+    getRegisteredFeedbackEmitters(action: Action): IFeedbackEmitter[] {
+        const result: IFeedbackEmitter[] = [];
+        this.registeredFeedback.forEach((actions, emitter) => {
+            if (actions.includes(action)) {
+                result.push(emitter);
+            }
+        });
+        return result;
+    }
+
+    protected async dispatchFeedback(actions: Action[], feedbackEmitter: IFeedbackEmitter): Promise<void> {
+        try {
+            const actionDispatcher = await this.actionDispatcher();
+            await actionDispatcher.dispatchAll(actions);
+            this.logger.info(this, `Dispatched feedback actions for ${feedbackEmitter}`);
+        } catch (reason) {
+            this.logger.error(this, 'Failed to dispatch feedback actions', reason);
+        }
+    }
+}

package/src/base/feedback/feedback-command.ts

@@ -0,0 +1,29 @@
+/********************************************************************************
+ * 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 { Command, CommandExecutionContext, CommandReturn } from '~glsp-sprotty';
+
+export abstract class FeedbackCommand extends Command {
+    // used by the `FeedbackAwareUpdateModelCommand`
+    readonly priority: number = 0;
+
+    undo(context: CommandExecutionContext): CommandReturn {
+        return context.root;
+    }
+
+    redo(context: CommandExecutionContext): CommandReturn {
+        return context.root;
+    }
+}

package/src/base/feedback/update-model-command.ts

@@ -0,0 +1,100 @@
+/********************************************************************************
+ * 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, optional } from 'inversify';
+import {
+    ActionHandlerRegistry,
+    Animation,
+    Command,
+    CommandActionHandler,
+    CommandExecutionContext,
+    CommandReturn,
+    ILogger,
+    MorphEdgesAnimation,
+    SModelRoot,
+    TYPES,
+    UpdateAnimationData,
+    UpdateModelAction,
+    UpdateModelCommand,
+    toTypeGuard
+} from '~glsp-sprotty';
+import { IFeedbackActionDispatcher } from './feedback-action-dispatcher';
+import { FeedbackCommand } from './feedback-command';
+
+/**
+ * A special {@link UpdateModelCommand} that retrieves all registered {@link Action}s from the {@link IFeedbackActionDispatcher}
+ * (if present) and applies their feedback to the `newRoot` before performing the update. This enables persistent client-side feedback
+ * across model updates initiated by the GLSP server.
+ */
+@injectable()
+export class FeedbackAwareUpdateModelCommand extends UpdateModelCommand {
+    @inject(TYPES.ILogger)
+    protected logger: ILogger;
+
+    @inject(TYPES.IFeedbackActionDispatcher)
+    @optional()
+    protected feedbackActionDispatcher: IFeedbackActionDispatcher;
+
+    protected actionHandlerRegistry?: ActionHandlerRegistry;
+
+    constructor(
+        @inject(TYPES.Action) action: UpdateModelAction,
+        @inject(TYPES.ActionHandlerRegistryProvider)
+        actionHandlerRegistryProvider: () => Promise<ActionHandlerRegistry>
+    ) {
+        super({ animate: true, ...action });
+        actionHandlerRegistryProvider().then(registry => (this.actionHandlerRegistry = registry));
+    }
+
+    protected override performUpdate(oldRoot: SModelRoot, newRoot: SModelRoot, context: CommandExecutionContext): CommandReturn {
+        if (this.feedbackActionDispatcher && this.actionHandlerRegistry) {
+            // Create a temporary context which defines the `newRoot` as `root`
+            // This way we do not corrupt the redo/undo behavior of the super class
+            const tempContext: CommandExecutionContext = {
+                ...context,
+                root: newRoot
+            };
+
+            const feedbackCommands = this.getFeedbackCommands(this.actionHandlerRegistry);
+            feedbackCommands.forEach(command => command.execute(tempContext));
+        }
+
+        return super.performUpdate(oldRoot, newRoot, context);
+    }
+
+    protected getFeedbackCommands(registry: ActionHandlerRegistry): Command[] {
+        const result: Command[] = [];
+        this.feedbackActionDispatcher.getRegisteredFeedback().forEach(action => {
+            const commands = registry
+                .get(action.kind)
+                .filter<CommandActionHandler>(toTypeGuard(CommandActionHandler))
+                .map(handler => handler.handle(action));
+            result.push(...commands);
+        });
+        // sort commands descanting by priority
+        return result.sort((a, b) => this.getPriority(b) - this.getPriority(a));
+    }
+
+    protected getPriority(command: Partial<FeedbackCommand>): number {
+        return command.priority ?? 0;
+    }
+
+    // Override the `createAnimations` implementation and remove the animation for edge morphing. Otherwise routing & reconnect
+    // handles flicker after each server update.
+    protected override createAnimations(data: UpdateAnimationData, root: SModelRoot, context: CommandExecutionContext): Animation[] {
+        const animations = super.createAnimations(data, root, context);
+        return animations.filter(animation => !(animation instanceof MorphEdgesAnimation));
+    }
+}

package/src/base/focus/focus-state-change-action.ts

@@ -0,0 +1,43 @@
+/********************************************************************************
+ * Copyright (c) 2021-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 { Action, hasBooleanProp } from '~glsp-sprotty';
+
+/**
+ * A `FocusStateChangedAction` is dispatched by the client whenever the
+ * diagram focus changes (i.e. focus loss or focus gain).
+ */
+export interface FocusStateChangedAction extends Action {
+    kind: typeof FocusStateChangedAction.KIND;
+    /**
+     * The new focus state of the diagram.
+     */
+    hasFocus: boolean;
+}
+
+export namespace FocusStateChangedAction {
+    export const KIND = 'focusStateChanged';
+
+    export function is(object: any): object is FocusStateChangedAction {
+        return Action.hasKind(object, KIND) && hasBooleanProp(object, 'hasFocus');
+    }
+
+    export function create(hasFocus = true): FocusStateChangedAction {
+        return {
+            kind: KIND,
+            hasFocus
+        };
+    }
+}

package/src/base/focus/focus-tracker.ts

@@ -0,0 +1,47 @@
+/********************************************************************************
+ * Copyright (c) 2021-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 } from 'inversify';
+import { Action, IActionHandler, ICommand, TYPES, ViewerOptions } from '~glsp-sprotty';
+import { FocusStateChangedAction } from './focus-state-change-action';
+
+@injectable()
+export class FocusTracker implements IActionHandler {
+    protected inActiveCssClass = 'inactive';
+    protected _hasFocus = true;
+
+    @inject(TYPES.ViewerOptions) protected options: ViewerOptions;
+
+    get hasFocus(): boolean {
+        return this._hasFocus;
+    }
+
+    handle(action: Action): void | Action | ICommand {
+        if (FocusStateChangedAction.is(action)) {
+            this._hasFocus = action.hasFocus;
+            const placeholder = document.getElementById(this.options.baseDiv);
+            if (!placeholder) {
+                return;
+            }
+            if (this.hasFocus) {
+                if (placeholder.classList.contains(this.inActiveCssClass)) {
+                    placeholder.classList.remove(this.inActiveCssClass);
+                }
+            } else {
+                placeholder.classList.add(this.inActiveCssClass);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,149 @@
+/********************************************************************************
+ * 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 } from 'inversify';
+import {
+    Action,
+    ActionHandlerRegistry,
+    ActionMessage,
+    Disposable,
+    DisposableCollection,
+    GLSPClient,
+    ILogger,
+    ModelSource,
+    RequestModelAction,
+    SModelRootSchema,
+    TYPES
+} from '~glsp-sprotty';
+/**
+ * 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;
+
+    protected _sourceUri?: string;
+    protected _glspClient?: GLSPClient;
+    protected toDispose = new DisposableCollection();
+
+    clientId: string;
+
+    get glspClient(): GLSPClient | undefined {
+        return this._glspClient;
+    }
+
+    get sourceUri(): string | undefined {
+        return this._sourceUri;
+    }
+
+    async connect(client: GLSPClient, clientId?: string): Promise<GLSPClient> {
+        if (clientId) {
+            this.clientId = clientId;
+        }
+        await client.start();
+        this.toDispose.push(client.onActionMessage(message => this.messageReceived(message), this.clientId));
+        this._glspClient = client;
+        return this._glspClient;
+    }
+
+    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: ActionHandlerRegistry): void {
+        // Registering actions here is discouraged and it's recommended
+        // to implemented dedicated action handlers.
+        if (!this.clientId) {
+            this.clientId = this.viewerOptions.baseDiv;
+        }
+    }
+
+    handle(action: Action): void {
+        // Handling additional actions here is discouraged and it's recommended
+        // to implemented dedicated action handlers.
+        if (RequestModelAction.is(action)) {
+            this._sourceUri = action.options?.sourceUri.toString();
+        }
+        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`
+         */
+        return newRoot;
+    }
+
+    dispose(): void {
+        this.toDispose.dispose();
+    }
+}

package/src/base/model/model-registry.ts

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2021-2022 EclipseSource and others.
+ * Copyright (c) 2021-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
@@ -14,7 +14,7 @@
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
 import { injectable } from 'inversify';
-import { SModelElement, SModelRegistry } from 'sprotty';
+import { SModelElement, SModelRegistry } from '~glsp-sprotty';
 
 @injectable()
 export class GLSPModelRegistry extends SModelRegistry {

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

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2020-2022 EclipseSource and others.
+ * Copyright (c) 2020-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
@@ -13,9 +13,8 @@
  *
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
-import { Action, Deferred, SetModelAction, UpdateModelAction } from '@eclipse-glsp/protocol';
 import { injectable } from 'inversify';
-import { InitializeCanvasBoundsAction } from 'sprotty';
+import { Action, Deferred, InitializeCanvasBoundsAction, SetModelAction, UpdateModelAction } from '~glsp-sprotty';
 
 /**
  * The constraint defining when the initialization of the GLSP model is completed.

package/src/base/ranked.ts

@@ -0,0 +1,42 @@
+/********************************************************************************
+ * 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 { AnyObject, hasNumberProp } from '~glsp-sprotty';
+
+/**
+ * A common interface for services/listeners that should be
+ * orderable by a type or rank/priority.
+ */
+export interface Ranked {
+    rank: number;
+}
+
+export namespace Ranked {
+    export const DEFAULT_RANK = 0;
+    export function is(object: unknown): object is Ranked {
+        return AnyObject.is(object) && hasNumberProp(object, 'rank');
+    }
+
+    /**
+     * Tries to retrieve the rank form the given object. If the object
+     * implements the {@link Ranked} interface the corresponding rank is returned
+     * otherwise the {@link DEFAULT_RANK} is returned.
+     * @param object
+     */
+    export function getRank(object: unknown): number {
+        return is(object) ? object.rank : DEFAULT_RANK;
+    }
+}

package/src/base/selection-clearing-mouse-listener.ts

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2020 EclipseSource and others.
+ * Copyright (c) 2020-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
@@ -14,7 +14,7 @@
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
 import { injectable } from 'inversify';
-import { MouseListener, SModelElement } from 'sprotty';
+import { MouseListener, SModelElement } from '~glsp-sprotty';
 
 /**
  * A mouse listener that clears the document selection on click