@eclipse-glsp/protocol/lib/action-protocol/element-navigation.d.ts

The protocol definition for client-server communication in GLSP

/********************************************************************************
 * 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
 * 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 { JsonPrimitive } from 'sprotty-protocol';
import { Action, RequestAction, ResponseAction } from './base-protocol';
import { Args, EditorContext } from './types';
/**
 * A `NavigationTarget` identifies the object we want to navigate to via its uri and may further provide a label to display to the user.
 * The corresponding namespace offers a set of utility function to interact with `NavigationTargets`.
 */
export interface NavigationTarget {
    /**
     * URI to identify the object we want to navigate to.
     */
    uri: string;
    /**
     * Optional label to display to the user.
     */
    label?: string;
    /**
     * Domain-specific arguments that may be interpreted directly or resolved further.
     */
    args?: Args;
}
export declare namespace NavigationTarget {
    function is(object: unknown): object is NavigationTarget;
    /**
     *  Generic key to store element ids as additional argument
     */
    const ELEMENT_IDS = "elementIds";
    /**
     * The separator that is used to store he values for the {@link ELEMENT_IDS} as a single string.
     */
    const ELEMENT_IDS_SEPARATOR = "&";
    /**
     *  Generic key ot store the line property of a {@link TextPosition} as additional argument.
     */
    const TEXT_LINE = "line";
    /**
     *  Generic key ot store the character property of a {@link TextPosition} as additional argument.
     */
    const TEXT_COLUMN = "column";
    /**
     * Denotes the position of the cursor in a text element.
     */
    interface TextPosition {
        line: number;
        /**
         * The character number within the line. Also refereed to as column.
         */
        character: number;
    }
    /**
     * Utility function to check wether the given {@link NavigationTarget} has additional arguments defined.
     * @param target The navigation target to check.
     * @returns `true` if the navigation target has a non-empty `args` property, `false`
     */
    function hasArguments(target: NavigationTarget): boolean;
    /**
     * Adds a new key-value pair to the additional arguments of the given {@link NavigationTarget}.
     * @param target The navigation target.
     * @param key The key of the new argument.
     * @param value The (primitive) value of the new argument.
     */
    function addArgument(target: NavigationTarget, key: string, value: JsonPrimitive): void;
    /**
     * Retrieves the element ids that have been stored with the generic {@link ELEMENT_IDS} key from the args of the
     * given target.
     * @param target The navigation target.
     * @returns An array with the parsed element ids. The array is empty if no {@link ELEMENT_IDS} key is present in the args
     * of the navigation target.
     */
    function getElementIds(target: NavigationTarget): string[];
    /**
     * Stores the given element ids in the given {@link NavigationTarget} as additional arguments using the generic {@link ELEMENT_IDS} key.
     * @param target The navigation target.
     * @param elementIds The element ids that should be stored.
     * @returns the value of the {@link ELEMENT_IDS} key after storing the given element ids.
     */
    function setElementIds(target: NavigationTarget, ...elementIds: string[]): string;
    /**
     * Stores the given {@link TextPosition} in the given {@link NavigationTarget} as additional arguments using
     * the generic {@link TEXT_LINE} & {@link TEXT_COLUMN} keys.
     * @param target The navigation target.
     * @param position The text position that should be stored.
     */
    function setTextPosition(target: NavigationTarget, position: TextPosition | undefined): void;
    /**
     * Retrieves the {@link TextPosition} that have been stored with the generic {@link TEXT_LINE} & {@link TEXT_COLUMN} keys
     * from the args of the given target.
     * @param target The navigation target.
     * @returns The parsed text position or `undefined` if one of the generic text keys is not present in the args
     * of the navigation target.
     */
    function getTextPosition(target: NavigationTarget): TextPosition | undefined;
}
/**
 * Action that is usually sent from the client to the server to request navigation targets for a specific navigation type such as
 * `documentation` or `implementation` in the given editor context.
 * The corresponding namespace declares the action kind as constant and offers helper functions for type guard checks
 * and creating new `RequestNavigationTargetsActions`.
 */
export interface RequestNavigationTargetsAction extends RequestAction<SetNavigationTargetsAction> {
    kind: typeof RequestNavigationTargetsAction.KIND;
    /**
     * Identifier of the type of navigation targets we want to retrieve, e.g., 'documentation', 'implementation', etc.
     */
    targetTypeId: string;
    editorContext: EditorContext;
}
export declare namespace RequestNavigationTargetsAction {
    const KIND = "requestNavigationTargets";
    function is(object: unknown): object is RequestNavigationTargetsAction;
    function create(options: {
        targetTypeId: string;
        editorContext: EditorContext;
        requestId?: string;
    }): RequestNavigationTargetsAction;
}
/**
 * Response action from the server following a {@link RequestNavigationTargetsAction}. It contains all available navigation targets for the
 * queried target type in the provided editor context. The server may also provide additional information using the arguments, e.g.,
 * warnings, that can be interpreted by the client.
 * The corresponding namespace declares the action kind as constant and offers helper functions for type guard checks
 * and creating new `SetNavigationTargetsActions`.
 */
export interface SetNavigationTargetsAction extends ResponseAction {
    kind: typeof SetNavigationTargetsAction.KIND;
    targets: NavigationTarget[];
    /**
     * Custom arguments that may be interpreted by the client.
     */
    args?: Args;
}
export declare namespace SetNavigationTargetsAction {
    const KIND = "setNavigationTargets";
    function is(object: unknown): object is SetNavigationTargetsAction;
    function create(targets: NavigationTarget[], options?: {
        args?: Args;
        responseId?: string;
    }): SetNavigationTargetsAction;
}
/**
 * Action that triggers the navigation to a particular navigation target, such as element IDs, queries, etc..
 * The corresponding namespace declares the action kind as constant and offers helper functions for type guard checks
 * and creating new `NavigateToTargetActions`.
 */
export interface NavigateToTargetAction extends Action {
    kind: typeof NavigateToTargetAction.KIND;
    target: NavigationTarget;
}
export declare namespace NavigateToTargetAction {
    const KIND = "navigateToTarget";
    function is(object: unknown): object is NavigateToTargetAction;
    function create(target: NavigationTarget): NavigateToTargetAction;
}
/**
 * If a client cannot navigate to a target directly, a {@link ResolveNavigationTargetAction} may be sent to the server to resolve the
 * navigation target to one or more model elements. This may be useful in cases where the resolution of each target is expensive or the
 * client architecture requires an indirection.
 * The corresponding namespace declares the action kind as constant and offers helper functions for type guard checks
 * and creating new `ResolveNavigationTargetActions`.
 */
export interface ResolveNavigationTargetAction extends RequestAction<SetResolvedNavigationTargetAction> {
    kind: typeof ResolveNavigationTargetAction.KIND;
    /**
     * The navigation target to resolve.
     */
    navigationTarget: NavigationTarget;
}
export declare namespace ResolveNavigationTargetAction {
    const KIND = "resolveNavigationTarget";
    function is(object: unknown): object is ResolveNavigationTargetAction;
    function create(navigationTarget: NavigationTarget, options?: {
        requestId?: string;
    }): ResolveNavigationTargetAction;
}
/**
 * An action sent from the server in response to a {@link ResolveNavigationTargetAction}. The response contains the resolved element ids
 * for the given target and may contain additional information in the args property.
 * The corresponding namespace declares the action kind as constant and offers helper functions for type guard checks
 * and creating new `SetResolvedNavigationTargetActions`.
 */
export interface SetResolvedNavigationTargetAction extends ResponseAction {
    kind: typeof SetResolvedNavigationTargetAction.KIND;
    /**
     * The element ids of the resolved navigation target.
     */
    elementIds: string[];
    /**
     * Custom arguments that may be interpreted by the client.
     */
    args?: Args;
}
export declare namespace SetResolvedNavigationTargetAction {
    const KIND = "setResolvedNavigationTarget";
    function is(object: unknown): object is SetResolvedNavigationTargetAction;
    function create(elementIds: string[], options?: {
        args?: Args;
        responseId?: string;
    }): SetResolvedNavigationTargetAction;
}
/**
 * If a {@link NavigationTarget} cannot be resolved or the resolved target is something that is not part of our source model, e.g.,
 * a separate documentation file, a {@link NavigateToExternalTargetAction} may be sent. Since the target it outside of the model scope such
 * an action would be typically handled by an integration layer (such as the surrounding IDE).
 * The corresponding namespace declares the action kind as constant and offers helper functions for type guard checks
 * and creating new `NavigateToExternalTargetActions`.
 */
export interface NavigateToExternalTargetAction extends Action {
    kind: typeof NavigateToExternalTargetAction.KIND;
    /**
     * The diagram-external target to which the client shall navigate.
     */
    target: NavigationTarget;
}
export declare namespace NavigateToExternalTargetAction {
    const KIND = "navigateToExternalTarget";
    function is(object: unknown): object is NavigateToExternalTargetAction;
    function create(target: NavigationTarget): NavigateToExternalTargetAction;
}
//# sourceMappingURL=element-navigation.d.ts.map