@jupyterlab/lsp 4.0.0-alpha.11 → 4.0.0-alpha.12

package/lib/adapters/adapter.d.ts

@@ -1,40 +1,34 @@
-import { JupyterFrontEnd } from '@jupyterlab/application';
+import { IDisposable } from '@lumino/disposable';
 import { CodeEditor } from '@jupyterlab/codeeditor';
 import { DocumentRegistry, IDocumentWidget } from '@jupyterlab/docregistry';
-import * as nbformat from '@jupyterlab/nbformat';
 import { ITranslator, TranslationBundle } from '@jupyterlab/translation';
-import { Signal } from '@lumino/signaling';
+import { ISignal, Signal } from '@lumino/signaling';
 import { LanguageIdentifier } from '../lsp';
 import { IVirtualPosition } from '../positioning';
 import { IDocumentConnectionData, ILSPCodeExtractorsManager, ILSPDocumentConnectionManager, ILSPFeatureManager } from '../tokens';
 import { IForeignContext, VirtualDocument } from '../virtual/document';
-export declare class StatusMessage {
-    /**
-     * The text message to be shown on the statusbar
-     */
-    message: string;
-    changed: Signal<StatusMessage, void>;
-    private timer;
-    constructor();
+export interface IEditorChangedData {
     /**
-     * Set the text message and (optionally) the timeout to remove it.
-     * @param message
-     * @param timeout - number of ms to until the message is cleaned;
-     *        -1 if the message should stay up indefinitely;
-     *        defaults to 3000ms (3 seconds)
+     * The CM editor invoking the change event.
      */
-    set(message: string, timeout?: number): void;
-    clear(): void;
-    private expireTimer;
-}
-export interface IEditorChangedData {
     editor: CodeEditor.IEditor;
 }
 export interface IAdapterOptions {
-    app: JupyterFrontEnd;
+    /**
+     * The LSP document and connection manager instance.
+     */
     connectionManager: ILSPDocumentConnectionManager;
+    /**
+     * The LSP feature manager instance.
+     */
     featureManager: ILSPFeatureManager;
+    /**
+     * The LSP foreign code extractor manager.
+     */
     foreignCodeExtractorsManager: ILSPCodeExtractorsManager;
+    /**
+     * The translator provider.
+     */
     translator?: ITranslator;
 }
 /**
@@ -43,49 +37,152 @@ export interface IAdapterOptions {
  * as this would make the logic of inspections caching impossible to maintain, thus the WidgetAdapter
  * has to handle that, keeping multiple connections and multiple virtual documents.
  */
-export declare abstract class WidgetAdapter<T extends IDocumentWidget> {
-    protected options: IAdapterOptions;
+export declare abstract class WidgetLSPAdapter<T extends IDocumentWidget> implements IDisposable {
     widget: T;
-    adapterConnected: Signal<WidgetAdapter<T>, IDocumentConnectionData>;
+    protected options: IAdapterOptions;
+    constructor(widget: T, options: IAdapterOptions);
+    /**
+     * Check if the adapter is disposed
+     */
+    get isDisposed(): boolean;
+    /**
+     * Check if the document contains multiple editors
+     */
+    get hasMultipleEditors(): boolean;
+    /**
+     * Get the ID of the internal widget.
+     */
+    get widgetId(): string;
+    /**
+     * Get the language identifier of the document
+     */
+    get language(): LanguageIdentifier;
+    /**
+     * Signal emitted when the adapter is connected.
+     */
+    get adapterConnected(): ISignal<WidgetLSPAdapter<T>, IDocumentConnectionData>;
+    /**
+     * Signal emitted when the active editor have changed.
+     */
+    get activeEditorChanged(): ISignal<WidgetLSPAdapter<T>, IEditorChangedData>;
+    /**
+     * Signal emitted when the adapter is disposed.
+     */
+    get disposed(): ISignal<WidgetLSPAdapter<T>, void>;
+    /**
+     * Signal emitted when the an editor is changed.
+     */
+    get editorAdded(): ISignal<WidgetLSPAdapter<T>, IEditorChangedData>;
+    /**
+     * Signal emitted when the an editor is removed.
+     */
+    get editorRemoved(): ISignal<WidgetLSPAdapter<T>, IEditorChangedData>;
+    /**
+     * Get the inner HTMLElement of the document widget.
+     */
+    abstract get wrapperElement(): HTMLElement;
+    /**
+     * Get current path of the document.
+     */
+    abstract get documentPath(): string;
+    /**
+     * Get the mime type of the document.
+     */
+    abstract get mimeType(): string;
+    /**
+     * Get the file extension of the document.
+     */
+    abstract get languageFileExtension(): string | undefined;
+    /**
+     * Get the activated CM editor.
+     */
+    abstract get activeEditor(): CodeEditor.IEditor | undefined;
+    /**
+     *  Get the list of CM editors in the document, there is only one editor
+     * in the case of file editor.
+     */
+    abstract get editors(): {
+        ceEditor: CodeEditor.IEditor;
+        type: string;
+    }[];
+    /**
+     * The virtual document is connected or not
+     */
     isConnected: boolean;
+    /**
+     * The LSP document and connection manager instance.
+     */
     connectionManager: ILSPDocumentConnectionManager;
+    /**
+     * The translator provider.
+     */
     trans: TranslationBundle;
-    protected isDisposed: boolean;
-    protected app: JupyterFrontEnd;
-    activeEditorChanged: Signal<WidgetAdapter<T>, IEditorChangedData>;
-    editorAdded: Signal<WidgetAdapter<T>, IEditorChangedData>;
-    editorRemoved: Signal<WidgetAdapter<T>, IEditorChangedData>;
+    /**
+     * Promise that resolves once the document is updated
+     */
     updateFinished: Promise<void>;
-    initialized: Promise<void>;
+    /**
+     * Promise that resolves once the adapter is initialized
+     */
+    ready: Promise<void>;
+    /**
+     * Internal virtual document of the adapter.
+     */
     virtualDocument: VirtualDocument;
+    /**
+     * Callback on connection closed event.
+     */
+    onConnectionClosed(_: ILSPDocumentConnectionManager, { virtualDocument }: IDocumentConnectionData): void;
+    /**
+     * Dispose the adapter.
+     */
+    dispose(): void;
+    /**
+     * Disconnect virtual document from the language server.
+     */
+    disconnect(): void;
+    /**
+     * Update the virtual document.
+     */
+    updateDocuments(): Promise<void>;
+    /**
+     * Callback called on the document changed event.
+     */
+    documentChanged(virtualDocument: VirtualDocument, document: VirtualDocument, isInit?: boolean): void;
     /**
      * (re)create virtual document using current path and language
      */
     abstract createVirtualDocument(): VirtualDocument;
+    /**
+     * Get the index of editor from the cursor position in the virtual
+     * document. Since there is only one editor, this method always return
+     * 0
+     *
+     * @param position - the position of cursor in the virtual document.
+     * @return - index of the virtual editor
+     */
     abstract getEditorIndexAt(position: IVirtualPosition): number;
+    /**
+     * Get the index of input editor
+     *
+     * @param ceEditor - instance of the code editor
+     */
     abstract getEditorIndex(ceEditor: CodeEditor.IEditor): number;
+    /**
+     * Get the wrapper of input editor.
+     *
+     * @param ceEditor
+     */
     abstract getEditorWrapper(ceEditor: CodeEditor.IEditor): HTMLElement;
-    protected constructor(options: IAdapterOptions, widget: T);
-    onConnectionClosed(_: ILSPDocumentConnectionManager, { virtualDocument }: IDocumentConnectionData): void;
-    dispose(): void;
-    abstract get documentPath(): string;
-    abstract get mimeType(): string;
-    get widgetId(): string;
-    get language(): LanguageIdentifier;
-    abstract get languageFileExtension(): string | undefined;
-    disconnect(): void;
     protected reloadConnection(): void;
+    /**
+     * Callback on document saved event.
+     */
     protected onSaveState(context: DocumentRegistry.IContext<DocumentRegistry.IModel>, state: DocumentRegistry.SaveState): void;
-    abstract activeEditor: CodeEditor.IEditor | undefined;
-    abstract get editors(): {
-        ceEditor: CodeEditor.IEditor;
-        type: nbformat.CellType;
-    }[];
+    protected _isDisposed: boolean;
     /**
-     * public for use in tests (but otherwise could be private)
+     * Connect the virtual document with the language server.
      */
-    updateDocuments(): Promise<void> | undefined;
-    get hasMultipleEditors(): boolean;
     protected onConnected(data: IDocumentConnectionData): Promise<void>;
     /**
      * Opens a connection for the document. The connection may or may
@@ -96,8 +193,10 @@ export declare abstract class WidgetAdapter<T extends IDocumentWidget> {
      * @param sendOpen whether to open the document immediately
      */
     protected connectDocument(virtualDocument: VirtualDocument, sendOpen?: boolean): Promise<void>;
+    /**
+     * Create the virtual document using current path and language.
+     */
     protected initVirtual(): void;
-    private onForeignDocumentClosed;
     /**
      * Handler for opening a document contained in a parent document. The assumption
      * is that the editor already exists for this, and as such the document
@@ -107,8 +206,37 @@ export declare abstract class WidgetAdapter<T extends IDocumentWidget> {
      * @param context information about the foreign VirtualDocument
      */
     protected onForeignDocumentOpened(_: VirtualDocument, context: IForeignContext): Promise<void>;
-    documentChanged(virtualDocument: VirtualDocument, document: VirtualDocument, isInit?: boolean): void;
-    private connect;
+    /**
+     * Signal emitted when the adapter is connected.
+     */
+    protected _adapterConnected: Signal<WidgetLSPAdapter<T>, IDocumentConnectionData>;
+    /**
+     * Signal emitted when the active editor have changed.
+     */
+    protected _activeEditorChanged: Signal<WidgetLSPAdapter<T>, IEditorChangedData>;
+    /**
+     * Signal emitted when an editor is changed.
+     */
+    protected _editorAdded: Signal<WidgetLSPAdapter<T>, IEditorChangedData>;
+    /**
+     * Signal emitted when an editor is removed.
+     */
+    protected _editorRemoved: Signal<WidgetLSPAdapter<T>, IEditorChangedData>;
+    /**
+     * Signal emitted when the adapter is disposed.
+     */
+    protected _disposed: Signal<WidgetLSPAdapter<T>, void>;
+    /**
+     * Callback called when a foreign document is closed,
+     * the associated signals with this virtual document
+     * are disconnected.
+     */
+    private _onForeignDocumentClosed;
+    /**
+     * Detect the capabilities for the document type then
+     * open the websocket connection with the language server.
+     */
+    private _connect;
     /**
      * Connect the change signal in order to update all virtual documents after a change.
      *
@@ -119,7 +247,9 @@ export declare abstract class WidgetAdapter<T extends IDocumentWidget> {
      * (range) updates this can be still implemented by comparison of before/after states of the
      * virtual documents, which is even more resilient and -obviously - editor-independent.
      */
-    private connectContentChangedSignal;
-    private onContentChanged;
-    abstract get wrapperElement(): HTMLElement;
+    private _connectContentChangedSignal;
+    /**
+     * Callback called when the content of the document have changed.
+     */
+    private _onContentChanged;
 }