@eclipse-glsp/server 1.1.0-RC05

package/src/common/features/model/model-submission-handler.ts

@@ -0,0 +1,110 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics 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 { GModelRootSchema } from '@eclipse-glsp/graph';
+import {
+    Action,
+    DirtyStateChangeReason,
+    MaybePromise,
+    RequestBoundsAction,
+    SetDirtyStateAction,
+    SetModelAction,
+    UpdateModelAction
+} from '@eclipse-glsp/protocol';
+import { inject, injectable, optional } from 'inversify';
+import { CommandStack } from '../../command/command-stack';
+import { DiagramConfiguration, ServerLayoutKind } from '../../diagram/diagram-configuration';
+import { LayoutEngine } from '../layout/layout-engine';
+import { GModelFactory } from './gmodel-factory';
+import { GModelSerializer } from './gmodel-serializer';
+import { ModelState } from './model-state';
+
+@injectable()
+export class ModelSubmissionHandler {
+    @inject(DiagramConfiguration)
+    protected diagramConfiguration: DiagramConfiguration;
+
+    @inject(GModelSerializer)
+    protected serializer: GModelSerializer;
+
+    @inject(GModelFactory)
+    protected modelFactory: GModelFactory;
+
+    @inject(ModelState)
+    protected modelState: ModelState;
+
+    @inject(LayoutEngine)
+    @optional()
+    protected layoutEngine: LayoutEngine;
+
+    @inject(CommandStack)
+    protected commandStack: CommandStack;
+
+    /**
+     * Returns a list of actions to update the client-side model, based on the specified <code>modelState</code>.
+     *
+     * These actions are not processed by this {@link ModelSubmissionHandler}, but should be either manually dispatched
+     * to the `ActionDispatcher`, or simply returned as the result of an `ActionHandler.execute()` method.
+     *
+     * @param reason The optional reason that caused the model update.
+     * @returns A list of actions to be processed in order to submit the model.
+     */
+    submitModel(reason?: DirtyStateChangeReason): MaybePromise<Action[]> {
+        this.modelFactory.createModel();
+        this.modelState.root.revision = (this.modelState.root.revision ?? 0) + 1;
+        const root = this.serializeGModel();
+
+        if (this.diagramConfiguration.needsClientLayout) {
+            return [RequestBoundsAction.create(root), SetDirtyStateAction.create(this.commandStack.isDirty, { reason })];
+        }
+        return [SetModelAction.create(root)];
+    }
+
+    /**
+     * Returns a list of actions to directly update the client-side model without any server- or client-side layouting.
+     *
+     * Typically `ActionHandler`s don't invoke this method but use {@link submitModel()}
+     * instead, as this is only used to eventually submit the model on the client directly after all layouting is already
+     * performed before. The only foreseen caller of this method is `ComputedBoundsActionHandler`.
+     *
+     * These actions are not processed by this {@link ModelSubmissionHandler}, but should be either manually dispatched
+     * to the `ActionDispatcher`, or simply returned as the result of an
+     * `ActionHandler.execute()` method.
+     *
+     * @param reason The optional reason that caused the model update.
+     * @returns A list of actions to be processed in order to submit the model.
+     */
+    async submitModelDirectly(reason?: DirtyStateChangeReason): Promise<Action[]> {
+        const root = this.serializeGModel();
+
+        if (this.diagramConfiguration.layoutKind === ServerLayoutKind.AUTOMATIC && this.layoutEngine) {
+            await this.layoutEngine.layout();
+        }
+        const result: Action[] = [];
+        result.push(
+            root.revision === 0
+                ? SetModelAction.create(root)
+                : UpdateModelAction.create(root, { animate: this.diagramConfiguration.animatedUpdate })
+        );
+        if (!this.diagramConfiguration.needsClientLayout) {
+            result.push(SetDirtyStateAction.create(this.commandStack.isDirty, { reason }));
+        }
+        return result;
+    }
+
+    protected serializeGModel(): GModelRootSchema {
+        return this.serializer.createSchema(this.modelState.root);
+    }
+}

package/src/common/features/model/request-model-action-handler.ts

@@ -0,0 +1,67 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics 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, RequestModelAction, ServerMessageAction, ServerStatusAction } from '@eclipse-glsp/protocol';
+import { inject, injectable } from 'inversify';
+import { ActionDispatcher } from '../../actions/action-dispatcher';
+import { ActionHandler } from '../../actions/action-handler';
+import { Logger } from '../../utils/logger';
+import { ModelState } from './model-state';
+import { ModelSubmissionHandler } from './model-submission-handler';
+import { SourceModelStorage } from './source-model-storage';
+
+@injectable()
+export class RequestModelActionHandler implements ActionHandler {
+    actionKinds = [RequestModelAction.KIND];
+
+    @inject(Logger)
+    private logger: Logger;
+
+    @inject(SourceModelStorage)
+    protected sourceModelStorage: SourceModelStorage;
+
+    @inject(ActionDispatcher)
+    protected actionDispatcher: ActionDispatcher;
+
+    @inject(ModelState)
+    protected modelState: ModelState;
+
+    @inject(ModelSubmissionHandler)
+    protected submissionHandler: ModelSubmissionHandler;
+
+    async execute(action: RequestModelAction): Promise<Action[]> {
+        this.logger.debug('Execute RequestModelAction:', action);
+        this.modelState.setAll(action.options ?? {});
+
+        this.notifyClient('Model loading in progress');
+        await this.sourceModelStorage.loadSourceModel(action);
+        // Clear the previous notification.
+        this.notifyClient();
+        return this.submissionHandler.submitModel();
+    }
+
+    /**
+     * Send a message and status notification with the given message to the client.
+     * An empty message is an indication for the client to clear previously received notifications.
+     * @param message The message that should be sent to the client
+     */
+    protected notifyClient(message = ''): void {
+        const severity = message.length > 0 ? 'INFO' : 'NONE';
+        this.actionDispatcher.dispatchAll(
+            ServerMessageAction.create(message, { severity }),
+            ServerStatusAction.create(message, { severity })
+        );
+    }
+}

package/src/common/features/model/save-model-action-handler.ts

@@ -0,0 +1,37 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics 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, SaveModelAction, SetDirtyStateAction } from '@eclipse-glsp/protocol';
+import { inject, injectable } from 'inversify';
+import { ActionHandler } from '../../actions/action-handler';
+import { CommandStack } from '../../command/command-stack';
+import { SourceModelStorage } from './source-model-storage';
+
+@injectable()
+export class SaveModelActionHandler implements ActionHandler {
+    actionKinds = [SaveModelAction.KIND];
+
+    @inject(CommandStack)
+    protected commandStack: CommandStack;
+
+    @inject(SourceModelStorage)
+    protected sourceModelStorage: SourceModelStorage;
+
+    async execute(action: SaveModelAction): Promise<Action[]> {
+        await this.sourceModelStorage.saveSourceModel(action);
+        this.commandStack.saveIsDone();
+        return [SetDirtyStateAction.create(this.commandStack.isDirty, { reason: 'save' })];
+    }
+}

package/src/common/features/model/source-model-storage.ts

@@ -0,0 +1,49 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics 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 { MaybePromise, RequestModelAction, SaveModelAction } from '@eclipse-glsp/protocol';
+
+export const SourceModelStorage = Symbol('SourceModelStorage');
+
+/**
+ * A source model storage handles the persistence of source models, i.e. loading and saving it from/into the model state.
+ *
+ * A `source model` is an arbitrary model from which the graph model of the diagram is to be created.
+ * Implementations of source model loaders are specific to the type of source model or persistence format that is used
+ * for a type of source model. A source model loader obtains the information on which source model shall loaded from a
+ * {@link RequestModelAction}; typically its client options. Once the source model is loaded, a model loader is expected
+ * to put the loaded source model into the model state for further processing, such as transforming the loaded model
+ * into a graph model (see GModelFactory).
+ * On `saveSourceModel(SaveModelAction)`, the source model storage persists the source model from the model state.
+ *
+ * @see ClientOptionsUtil
+ * @see GModelFactory
+ */
+export interface SourceModelStorage {
+    /**
+     * Loads a source model into the `modelState`.
+     *
+     * @param action Action sent by the client to specifying the information needed to load the source model.
+     */
+    loadSourceModel(action: RequestModelAction): MaybePromise<void>;
+
+    /**
+     * Saves the source model from the `modelState`.
+     * Implementations are expected to throw an error if the save didn't work.
+     *
+     * @param action Action sent by the client to specifying the information needed to save the source model.
+     */
+    saveSourceModel(action: SaveModelAction): MaybePromise<void>;
+}

package/src/common/features/navigation/json-opener-options.ts

@@ -0,0 +1,69 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics 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
+ ********************************************************************************/
+export class JsonOpenerOptions {
+    selection: TextSelection;
+
+    constructor(selection?: TextSelection) {
+        if (selection) {
+            this.selection = selection;
+        }
+    }
+
+    public toString(): string {
+        return `JsonOpenerOptions [selection=${this.selection}]`;
+    }
+
+    public toJson(): string {
+        return JsonOpenerOptions.toJson(this);
+    }
+
+    public static toJson(options: JsonOpenerOptions): string {
+        return JSON.stringify(options);
+    }
+
+    public static fromJson(options: string): JsonOpenerOptions | undefined {
+        const parsed = JSON.parse(options);
+        return parsed instanceof JsonOpenerOptions ? parsed : undefined;
+    }
+}
+
+export class TextSelection {
+    start: LinePosition;
+    end: LinePosition;
+
+    constructor(start: LinePosition, end: LinePosition) {
+        this.start = start;
+        this.end = end;
+    }
+
+    public toString(): string {
+        return `TextSelection [start=${this.start}, end=${this.end}]`;
+    }
+}
+
+export class LinePosition {
+    line: number;
+    character: number;
+
+    constructor(line: number, character: number) {
+        this.line = line;
+        this.character = character;
+    }
+
+    public toString(): string {
+        return `LinePosition [line=${this.line}, character=${this.character}]`;
+    }
+}

package/src/common/features/navigation/navigation-target-provider-registry.ts

@@ -0,0 +1,36 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics 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 { multiInject, optional } from 'inversify';
+import { NavigationTargetProviders } from '../../di/service-identifiers';
+import { Registry } from '../../utils/registry';
+import { NavigationTargetProvider } from './navigation-target-provider';
+
+export const NavigationTargetProviderRegistry = Symbol('NavigationTargetProviderRegistry');
+
+/**
+ * This registry keeps track of registered {@link NavigationTargetProvider} for a certain target types.
+ */
+export interface NavigationTargetProviderRegistry extends Registry<string, NavigationTargetProvider> {}
+
+export class DefaultNavigationTargetProviderRegistry
+    extends Registry<string, NavigationTargetProvider>
+    implements NavigationTargetProviderRegistry
+{
+    constructor(@multiInject(NavigationTargetProviders) @optional() navigationTargetProviders: NavigationTargetProvider[] = []) {
+        super();
+        navigationTargetProviders.forEach(provider => this.register(provider.targetTypeId, provider));
+    }
+}

package/src/common/features/navigation/navigation-target-provider.ts

@@ -0,0 +1,50 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics 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 { EditorContext, NavigationTarget } from '@eclipse-glsp/protocol';
+
+export const NavigationTargetProvider = Symbol('NavigationTargetProviders');
+
+/**
+ * This provider retrieves navigation targets for its target type from a given {@link EditorContext}.
+ */
+export interface NavigationTargetProvider {
+    /**
+     * Specifies the navigation targets for the given target type.
+     *
+     * If the `args` of a returned {@link NavigationTarget} contain a
+     * {@link NavigationTarget.ELEMENT_IDS_SEPARATOR}, GLSP diagram clients should navigate to
+     * the model elements with the specified ID within the current diagram. Multiple element
+     * IDs can be concatenated with {@link NavigationTarget.ELEMENT_IDS_SEPARATOR}.
+     *
+     * If the `args` of a returned {@link NavigationTarget} contain a property
+     * `JSON_OPENER_OPTIONS` and its uri is outside of the current diagram, the string
+     * value of the `JSON_OPENER_OPTIONS` property will be parsed as JSON
+     * and merged into the opener options by the Theia integration of the GLSP client.
+     * This allows GLSP servers to pass additional opener options, such as a selection, etc.
+     * Other clients (non-Theia clients) should behave the same way.
+     *
+     * @param editorContext The editor context
+     * @returns the list of navigation targets
+     */
+    getTargets(editorContext: EditorContext): NavigationTarget[];
+
+    /**
+     * Returns the targetTypeId of the provider.
+     *
+     * @returns The targetTypeId of the provider.
+     */
+    targetTypeId: string;
+}

package/src/common/features/navigation/navigation-target-resolution.ts

@@ -0,0 +1,22 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics 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 { Args } from '@eclipse-glsp/protocol';
+
+export class NavigationTargetResolution {
+    static readonly EMPTY = new NavigationTargetResolution([]);
+
+    constructor(readonly elementIds: string[], readonly args?: Args) {}
+}

package/src/common/features/navigation/navigation-target-resolver.ts

@@ -0,0 +1,61 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics 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 { Args, MaybePromise, NavigationTarget } from '@eclipse-glsp/protocol';
+import { injectable } from 'inversify';
+import { NavigationTargetResolution } from './navigation-target-resolution';
+
+@injectable()
+export abstract class NavigationTargetResolver {
+    readonly INFO = 'info';
+    readonly WARNING = 'warning';
+    readonly ERROR = 'error';
+
+    abstract resolve(navigationTarget: NavigationTarget): MaybePromise<NavigationTargetResolution>;
+
+    createArgs(): Args {
+        return {};
+    }
+
+    createArgsWithInfo(message: string): Args {
+        const args = this.createArgs();
+        this.addInfo(message, args);
+        return args;
+    }
+
+    createArgsWithWarning(message: string): Args {
+        const args = this.createArgs();
+        this.addWarning(message, args);
+        return args;
+    }
+
+    createArgsWithError(message: string): Args {
+        const args = this.createArgs();
+        this.addError(message, args);
+        return args;
+    }
+
+    addInfo(message: string, args: Args): void {
+        args[this.INFO] = message;
+    }
+
+    addWarning(message: string, args: Args): void {
+        args[this.WARNING] = message;
+    }
+
+    addError(message: string, args: Args): void {
+        args[this.ERROR] = message;
+    }
+}

package/src/common/features/navigation/request-navigation-targets-action-handler.ts

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics 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, MaybePromise, NavigationTarget, RequestNavigationTargetsAction, SetNavigationTargetsAction } from '@eclipse-glsp/protocol';
+import { injectable } from 'inversify';
+import { inject } from 'inversify/lib/annotation/inject';
+import { ActionHandler } from '../../actions/action-handler';
+import { NavigationTargetProviderRegistry } from './navigation-target-provider-registry';
+
+@injectable()
+export class RequestNavigationTargetsActionHandler implements ActionHandler {
+    actionKinds = [RequestNavigationTargetsAction.KIND];
+
+    @inject(NavigationTargetProviderRegistry)
+    protected navigationTargetProviderRegistry: NavigationTargetProviderRegistry;
+
+    execute(action: RequestNavigationTargetsAction): MaybePromise<Action[]> {
+        const editorContext = action.editorContext;
+        const allTargets: NavigationTarget[] = [];
+        const provider = this.navigationTargetProviderRegistry.get(action.targetTypeId);
+        if (provider) {
+            const targets = provider.getTargets(editorContext);
+            targets.forEach(target => allTargets.push(target));
+        }
+        return [SetNavigationTargetsAction.create(allTargets, { args: editorContext.args })];
+    }
+}

package/src/common/features/navigation/resolve-navigation-targets-action-handler.ts

@@ -0,0 +1,42 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics 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, ResolveNavigationTargetAction, SetResolvedNavigationTargetAction } from '@eclipse-glsp/protocol';
+import { inject, injectable, optional } from 'inversify';
+import { ActionHandler } from '../../actions/action-handler';
+import { Logger } from '../../utils/logger';
+import { NavigationTargetResolver } from './navigation-target-resolver';
+
+@injectable()
+export class ResolveNavigationTargetsActionHandler implements ActionHandler {
+    actionKinds = [ResolveNavigationTargetAction.KIND];
+
+    @inject(Logger)
+    protected logger: Logger;
+
+    @inject(NavigationTargetResolver)
+    @optional()
+    protected readonly navigationTargetResolver: NavigationTargetResolver;
+
+    async execute(action: ResolveNavigationTargetAction): Promise<Action[]> {
+        if (!this.navigationTargetResolver) {
+            this.logger.warn('Could not resolve navigation target. No implementation for: NavigationTargetResolver has been bound');
+            return [];
+        }
+        const target = action.navigationTarget;
+        const resolution = await this.navigationTargetResolver.resolve(target);
+        return [SetResolvedNavigationTargetAction.create(resolution.elementIds, { args: resolution.args })];
+    }
+}

package/src/common/features/popup/popup-model-factory.ts

@@ -0,0 +1,38 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics 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 { GModelElement, GModelRoot } from '@eclipse-glsp/graph';
+import { RequestPopupModelAction } from '@eclipse-glsp/protocol';
+
+export const PopupModelFactory = Symbol('PopupModelFactory');
+
+/**
+ * A PopupModelFactory creates a popup model for the given element.
+ * A popup model is a {@link GHtmlRoot} that is self contained and not part of the diagram model.
+ * In contrast to diagram elements popup models typically don't contain dynamically rendered {@link GModelElement}s and
+ * use{@link GPreRenderedElement}s that contain server-side computed html or svg code instead.
+ */
+export interface PopupModelFactory {
+    /**
+     * Returns an {@link GModelRoot} for a given {@link GModelElement} triggered by a
+     * {@link RequestPopupModelAction}.
+     *
+     * @param element The element to create the popup model for.
+     * @param action  The {@link RequestPopupModelAction} that triggered this popup model creation.
+     * @returns An optional {@link GHtmlRoot} for a given {@link GModelElement}.
+     */
+    createPopupModel(element: GModelElement, action: RequestPopupModelAction): GModelRoot | undefined;
+}