@eclipse-glsp/client 1.1.0-next.fe0b297.182 → 2.0.0

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 '@eclipse-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,
+    GModelRoot,
+    TYPES,
+    UpdateAnimationData,
+    UpdateModelAction,
+    UpdateModelCommand,
+    toTypeGuard
+} from '@eclipse-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: GModelRoot, newRoot: GModelRoot, 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: GModelRoot, 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 '@eclipse-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,58 @@
+/********************************************************************************
+ * 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 '@eclipse-glsp/sprotty';
+import { FocusStateChangedAction } from './focus-state-change-action';
+
+@injectable()
+export class FocusTracker implements IActionHandler {
+    protected inActiveCssClass = 'inactive';
+    protected _hasFocus = true;
+    protected _focusElement: HTMLOrSVGElement | null;
+    protected _diagramElement: HTMLElement | null;
+
+    @inject(TYPES.ViewerOptions) protected options: ViewerOptions;
+
+    get hasFocus(): boolean {
+        return this._hasFocus;
+    }
+
+    get focusElement(): HTMLOrSVGElement | null {
+        return this._focusElement;
+    }
+
+    get diagramElement(): HTMLElement | null {
+        return this._diagramElement;
+    }
+
+    handle(action: Action): void | Action | ICommand {
+        if (FocusStateChangedAction.is(action)) {
+            this._hasFocus = action.hasFocus;
+            this._focusElement = document.activeElement as HTMLOrSVGElement | null;
+            this._diagramElement = document.getElementById(this.options.baseDiv);
+            if (!this._diagramElement) {
+                return;
+            }
+            if (this.hasFocus) {
+                if (this._diagramElement.classList.contains(this.inActiveCssClass)) {
+                    this._diagramElement.classList.remove(this.inActiveCssClass);
+                }
+            } else {
+                this._diagramElement.classList.add(this.inActiveCssClass);
+            }
+        }
+    }
+}

package/src/base/model/diagram-loader.ts

@@ -0,0 +1,215 @@
+/********************************************************************************
+ * 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, multiInject, optional, postConstruct } from 'inversify';
+import {
+    AnyObject,
+    ApplicationIdProvider,
+    Args,
+    EMPTY_ROOT,
+    GLSPClient,
+    InitializeParameters,
+    MaybePromise,
+    RequestModelAction,
+    SetModelAction,
+    StatusAction,
+    TYPES,
+    hasNumberProp
+} from '@eclipse-glsp/sprotty';
+import { GLSPActionDispatcher } from '../action-dispatcher';
+import { Ranked } from '../ranked';
+import { GLSPModelSource } from './glsp-model-source';
+import { ModelInitializationConstraint } from './model-initialization-constraint';
+
+/**
+ * Configuration options for a specific GLSP diagram instance.
+ */
+export interface IDiagramOptions {
+    /**
+     * Unique id associated with this diagram. Used on the server side to identify the
+     * corresponding client session.
+     */
+    clientId: string;
+    /**
+     * The diagram type i.e. diagram language this diagram is associated with.
+     */
+    diagramType: string;
+    /**
+     * The provider function to retrieve the GLSP client used by this diagram to communicate with the server.
+     * Multiple invocations of the provder function should always return the same `GLSPClient` instance.
+     */
+    glspClientProvider: () => Promise<GLSPClient>;
+    /**
+     * The file source URI associated with this diagram.
+     */
+    sourceUri?: string;
+    /**
+     * The initial edit mode of diagram. Defaults to `editable`.
+     */
+    editMode?: string;
+}
+
+/**
+ * Services that implement startup hooks which are invoked during the {@link DiagramLoader.load} process.
+ * Typically used to dispatch additional initial actions and/or activate UI extensions on startup.
+ * Execution order is derived by the `rank` property of the service. If not present, the {@link Ranked.DEFAULT_RANK} will be assumed.
+ */
+export interface IDiagramStartup extends Partial<Ranked> {
+    /**
+     * Hook for services that should be executed before the underlying GLSP client is configured and the server is initialized.
+     */
+    preInitialize?(): MaybePromise<void>;
+    /**
+     * Hook for services that should be executed before the initial model loading request (i.e. `RequestModelAction`) but
+     * after the underlying GLSP client has been configured and the server is initialized.
+     */
+    preRequestModel?(): MaybePromise<void>;
+    /**
+     * Hook for services that should be executed after the initial model loading request (i.e. `RequestModelAction`).
+     * Note that this hook is invoked directly after the `RequestModelAction` has been dispatched. It does not necessarily wait
+     * until the client-server update roundtrip is completed. If you need to wait until the diagram is fully initialized use the
+     * {@link postModelInitialization} hook.
+     */
+    postRequestModel?(): MaybePromise<void>;
+    /* Hook for services that should be executed after the diagram model is fully initialized
+     * (i.e. `ModelInitializationConstraint` is completed).
+     */
+    postModelInitialization?(): MaybePromise<void>;
+}
+
+export namespace IDiagramStartup {
+    export function is(object: unknown): object is IDiagramStartup {
+        return (
+            AnyObject.is(object) &&
+            hasNumberProp(object, 'rank', true) &&
+            ('preInitialize' in object ||
+                'preRequestModel' in object ||
+                'postRequestModel' in object ||
+                'postModelInitialization' in object)
+        );
+    }
+}
+
+export interface DiagramLoadingOptions {
+    /**
+     * Optional custom options that should be used the initial {@link RequestModelAction}.
+     * These options will be merged with the default options (`diagramType` and `sourceUri`).
+     * Defaults to an empty object if not defined.
+     */
+    requestModelOptions?: Args;
+
+    /**
+     * Optional partial {@link InitializeParameters} that should be used for `initializeServer` request if the underlying
+     * {@link GLSPClient} has not been initialized yet.
+     */
+    initializeParameters?: Partial<InitializeParameters>;
+
+    /**
+     * Flag to enable/disable client side notifications during the loading process.
+     * Defaults to `true` if not defined
+     */
+    enableNotifications?: boolean;
+}
+
+export interface ResolvedDiagramLoadingOptions {
+    requestModelOptions: Args;
+    initializeParameters: InitializeParameters;
+    enableNotifications: boolean;
+}
+
+/**
+ * The central component responsible for initializing the diagram and loading the graphical model
+ * from the GLSP server.
+ * Invoking the {@link DiagramLoader.load} method is typically the first operation that is executed after
+ * a diagram DI container has been created.
+ */
+@injectable()
+export class DiagramLoader {
+    @inject(TYPES.IDiagramOptions)
+    protected options: IDiagramOptions;
+
+    @inject(GLSPActionDispatcher)
+    protected actionDispatcher: GLSPActionDispatcher;
+
+    @multiInject(TYPES.IDiagramStartup)
+    @optional()
+    protected diagramStartups: IDiagramStartup[] = [];
+
+    @inject(GLSPModelSource)
+    protected modelSource: GLSPModelSource;
+
+    @inject(ModelInitializationConstraint)
+    protected modelInitializationConstraint: ModelInitializationConstraint;
+
+    @postConstruct()
+    protected postConstruct(): void {
+        this.diagramStartups.sort((a, b) => Ranked.getRank(a) - Ranked.getRank(b));
+    }
+
+    async load(options: DiagramLoadingOptions = {}): Promise<void> {
+        const resolvedOptions: ResolvedDiagramLoadingOptions = {
+            requestModelOptions: {
+                sourceUri: this.options.sourceUri ?? '',
+                diagramType: this.options.diagramType,
+                ...options.requestModelOptions
+            },
+            initializeParameters: {
+                applicationId: ApplicationIdProvider.get(),
+                protocolVersion: GLSPClient.protocolVersion,
+                ...options.initializeParameters
+            },
+            enableNotifications: options.enableNotifications ?? true
+        };
+        // Set empty place holder model until actual model from server is available
+        await this.actionDispatcher.dispatch(SetModelAction.create(EMPTY_ROOT));
+        await this.invokeStartupHook('preInitialize');
+        await this.initialize(resolvedOptions);
+        await this.invokeStartupHook('preRequestModel');
+        await this.requestModel(resolvedOptions);
+        await this.invokeStartupHook('postRequestModel');
+        this.modelInitializationConstraint.onInitialized(() => this.invokeStartupHook('postModelInitialization'));
+    }
+
+    protected async invokeStartupHook(hook: keyof Omit<IDiagramStartup, 'rank'>): Promise<void> {
+        for (const startup of this.diagramStartups) {
+            await startup[hook]?.();
+        }
+    }
+
+    protected async requestModel(options: ResolvedDiagramLoadingOptions): Promise<void> {
+        const response = await this.actionDispatcher.request<SetModelAction>(
+            RequestModelAction.create({ options: options.requestModelOptions })
+        );
+        return this.actionDispatcher.dispatch(response);
+    }
+
+    protected async initialize(options: ResolvedDiagramLoadingOptions): Promise<void> {
+        if (options.enableNotifications) {
+            await this.actionDispatcher.dispatch(StatusAction.create('Initializing...', { severity: 'INFO' }));
+        }
+
+        const glspClient = await this.options.glspClientProvider();
+        await glspClient.start();
+        if (!glspClient.initializeResult) {
+            await glspClient.initializeServer(options.initializeParameters);
+        }
+        this.modelSource.configure(glspClient);
+
+        if (options.enableNotifications) {
+            this.actionDispatcher.dispatch(StatusAction.create('', { severity: 'NONE' }));
+        }
+    }
+}

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,
+    GModelRootSchema,
+    ILogger,
+    InitializeClientSessionParameters,
+    InitializeResult,
+    ModelSource,
+    TYPES
+} from '@eclipse-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: GModelRootSchema;
+    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: GModelRootSchema): GModelRootSchema {
+        /* 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(): GModelRootSchema {
+        return this._currentRoot;
+    }
+
+    @preDestroy()
+    dispose(): void {
+        this.toDispose.dispose();
+    }
+}